wiki-setup

SKILL.md

Obsidian Setup — Vault Initialization

You are setting up a new Obsidian wiki vault (or repairing an existing one).

Step 1: Create .env

If .env doesn't exist, create it from .env.example. Ask the user for:

Where should the vault live? → OBSIDIAN_VAULT_PATH

Default: ~/Documents/obsidian-wiki-vault

Must be an absolute path (after expansion)

Where are your source documents? → OBSIDIAN_SOURCES_DIR

Can be multiple paths, comma-separated

Default: ~/Documents

Want to import Claude history? → CLAUDE_HISTORY_PATH

Default: auto-discovers from ~/.claude

Set explicitly if Claude data is elsewhere

Have QMD installed? → QMD_WIKI_COLLECTION / QMD_PAPERS_COLLECTION / QMD_TRANSPORT

Optional. Enables semantic search in wiki-query and source discovery in wiki-ingest.

Default to QMD_TRANSPORT=mcp unless the user wants the agent to call the local qmd CLI directly.

If using CLI mode, set QMD_CLI_SEARCH_MODE=quality by default; suggest balanced if reranking is too slow.

If unsure, skip for now — both skills fall back to Grep automatically.

Install instructions: see .env.example (QMD section).

Token budget warning threshold? → WIKI_TOKEN_WARN_THRESHOLD

Default: 100000 (warn when full-wiki read would cost > 100K tokens)

Set to 0 to disable the warning entirely

wiki-status shows a token footprint table and emits this warning automatically

Enable staged writes? → WIKI_STAGED_WRITES

Default: unset / false (pages written directly to their final location)

Set to true for team wikis, high-stakes domains, or any vault where the human wants final say on every LLM-written page

When enabled: all new/updated pages land in _staging/ first; run /wiki-stage-commit to review and promote them

wiki-status shows a "Staged writes pending" count when files are waiting

Step 2: Create Vault Directory Structure

mkdir -p "$OBSIDIAN_VAULT_PATH"/{concepts,entities,skills,references,synthesis,journal,projects,_archives,_raw,_staging,.obsidian}

.obsidian/ — Obsidian's own config. Creates vault recognition.

projects/ — Per-project knowledge (populated during ingest).

_archives/ — Stores wiki snapshots for rebuild/restore operations.

_raw/ — Staging area for unprocessed drafts. Drop rough notes here; wiki-ingest will promote them to proper wiki pages and move the originals into _raw/_archived/ (created on first use).

_staging/ — Review queue for LLM-written pages when WIKI_STAGED_WRITES=true. Pages here are not visible in Obsidian's graph until promoted via /wiki-stage-commit.

Step 3: Create Special Files

index.md

---
title: Wiki Index
---

# Wiki Index

*This index is automatically maintained. Last updated: TIMESTAMP*

## Concepts

*No pages yet. Use `wiki-ingest` to add your first source.*

## Entities

## Skills

## References

## Synthesis

## Journal

log.md

---
title: Wiki Log
---

# Wiki Log

- [TIMESTAMP] INIT vault_path="OBSIDIAN_VAULT_PATH" categories=concepts,entities,skills,references,synthesis,journal

hot.md

---
title: Hot Cache
updated: TIMESTAMP
---

# Hot Cache

*A ~500-word semantic snapshot of recent activity. Updated after every major write operation.*

## Recent Activity

- [TIMESTAMP] INIT — vault created at OBSIDIAN_VAULT_PATH

## Active Threads

*None yet — start ingesting sources to populate.*

## Key Takeaways

*None yet.*

## Flagged Contradictions

*None yet.*

Step 4: Create .obsidian Configuration

Create minimal Obsidian config for a good out-of-box experience:

.obsidian/app.json

{
  "strictLineBreaks": false,
  "showFrontmatter": false,
  "defaultViewMode": "preview",
  "livePreview": true
}

.obsidian/appearance.json

{
  "baseFontSize": 16
}

Step 5: Recommend Obsidian Plugins

Tell the user about these recommended community plugins (they install manually):

Dataview — Query page metadata, create dynamic tables. Essential for a wiki.

Graph Analysis — Enhanced graph view for exploring connections.

Templater — If they want to create pages manually using templates.

Obsidian Git — Auto-backup the vault to a git repo.

Step 6: Verify Setup

Run a quick sanity check:

 Vault directory exists with: concepts/, entities/, skills/, references/, synthesis/, journal/, projects/, _archives/, _raw/

 index.md exists at vault root

 log.md exists at vault root

 hot.md exists at vault root

 .env has OBSIDIAN_VAULT_PATH set

 .obsidian/ directory exists

 _staging/ directory exists (required even when WIKI_STAGED_WRITES is not set — created on setup for future use)

 Source directories (if configured) exist and are readable

Report the results and tell the user they can now:

Open the vault in Obsidian (File → Open Vault → select the directory)

Run wiki-status to see what's available to ingest

Run wiki-ingest to add their first sources

Run claude-history-ingest to mine their Claude conversations

Run codex-history-ingest to mine their Codex sessions (if they use Codex)

Run wiki-status again anytime to check the delta

Optional: Install the Stop Hook (Auto-Capture)

Ask the user: "Want to auto-capture findings at session end?"

If yes, install the Stop hook into their global Claude Code settings so that every session
with meaningful work automatically prompts /wiki-capture --quick before closing.

What the hook does: reads the session transcript on Stop, counts file edits and shell
calls, and if significant work happened, asks Claude to run /wiki-capture --quick once.
The wiki-capture quick-mode KEEP/SKIP gate prevents noise — routine or
inconclusive sessions are skipped automatically.

Installation steps:

Find the obsidian-wiki repo path (the directory where this skill lives). If
OBSIDIAN_WIKI_REPO is set in config, use that. Otherwise, check common locations:
~/Documents/projects/obsidian-wiki, ~/obsidian-wiki, or ask the user.

Merge the hook entry into ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash <REPO_PATH>/.claude/hooks/wiki-stop-capture.sh"
          }
        ]
      }
    ]
  }
}

If ~/.claude/settings.json already exists and has a hooks.Stop array, append the new
entry rather than replacing — don't clobber existing hooks.

Confirm: "Stop hook installed. Claude Code will prompt /wiki-capture --quick at the
end of any session where you write files or run ≥ 4 shell commands."

To uninstall later: remove the hook entry from ~/.claude/settings.json or set
HIVEMIND_CAPTURE=false in your shell to skip capture for a single session.

Optional: Refresh QMD After Setup

If QMD_WIKI_COLLECTION is configured and the local QMD CLI is available, run qmd update after the initial vault files exist so the fresh vault is immediately queryable. No embedding pass is usually needed at setup time because the vault starts empty, so a plain update is enough unless you have already populated pages.