Codex History Ingest — Conversation Mining

You are extracting knowledge from the user's past Codex sessions and distilling it into the Obsidian wiki. Session logs are rich but noisy: focus on durable knowledge, not operational telemetry.

This skill can be invoked directly or via the wiki-history-ingest router (/wiki-history-ingest codex).

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and CODEX_HISTORY_PATH (defaults to ~/.codex)
2. Read .manifest.json at the vault root to check what has already been ingested
3. Read index.md at the vault root to understand what the wiki already contains

Ingest Modes

Append Mode (default)

Check .manifest.json for each source file. Only process:

• Files not in the manifest (new session rollouts, new index files)
• Files whose modification time is newer than ingested_at in the manifest

Use this mode for regular syncs.

Full Mode

Process everything regardless of manifest. Use after wiki-rebuild or if the user explicitly asks for a full re-ingest.

Codex Data Layout

Codex stores local artifacts under ~/.codex/.

~/.codex/
├── sessions/                          # Session rollout logs by date
│   └── YYYY/MM/DD/
│       └── rollout-<timestamp>-<id>.jsonl
├── archived_sessions/                 # Archived rollout logs
├── session_index.jsonl                # Lightweight index of thread id/name/updated_at
├── history.jsonl                      # Local transcript history (if persistence enabled)
├── config.toml                        # User config (contains history settings)
└── state_*.sqlite / logs_*.sqlite     # Runtime DBs (usually skip)

Key data sources ranked by value

1. session_index.jsonl — best inventory source for IDs, titles, and freshness
2. sessions/**/rollout-*.jsonl — rich structured transcript events
3. history.jsonl — useful fallback/timeline aid if enabled

Avoid ingesting SQLite internals unless the user explicitly asks.

Step 1: Survey and Compute Delta

Scan CODEX_HISTORY_PATH and compare against .manifest.json:

• ~/.codex/session_index.jsonl
• ~/.codex/sessions/**/rollout-*.jsonl
• ~/.codex/archived_sessions/** (optional; only if user asks for archived history)
• ~/.codex/history.jsonl (optional fallback)

Classify each file:

• New — not in manifest
• Modified — in manifest but file is newer than ingested_at
• Unchanged — already ingested and unchanged

Report a concise delta summary before deep parsing.

Step 2: Parse Session Index First

session_index.jsonl typically has entries like:

{"id":"...","thread_name":"...","updated_at":"..."}

Use it to:

• Build a canonical session inventory
• Prioritize recent/high-signal sessions
• Map rollout IDs to human-readable thread names

Step 3: Parse Rollout JSONL Safely

Each rollout-*.jsonl line is an event envelope with:

{
  "timestamp": "...",
  "type": "session_meta|turn_context|event_msg|response_item",
  "payload": { ... }
}

Extraction rules

• Prioritize user intent and assistant-visible outputs
• Favor response_item records with user/assistant message content
• Use event_msg selectively for meaningful milestones; ignore pure telemetry
• Treat session_meta as metadata (cwd, model, ids), not user knowledge

Skip/noise filters

• Token accounting events
• Tool plumbing with no semantic content
• Raw command output unless it contains reusable decisions/patterns
• Repeated plan snapshots unless they add novel decisions

Critical privacy filter

Rollout logs can include injected instructions, tool payloads, and sensitive text. Do not ingest verbatim system/developer prompts or secrets.

• Remove API keys, tokens, passwords, credentials
• Redact private identifiers unless relevant and approved
• Summarize instead of quoting raw transcripts

Step 4: Cluster by Topic

Do not create one wiki page per session.

• Group by stable topics across many sessions
• Split mixed sessions into separate themes
• Merge recurring concepts across dates/projects
• Use cwd from metadata to infer project scope

Step 5: Distill into Wiki Pages

Route extracted knowledge using existing wiki conventions:

• Project-specific architecture/process -> projects/<name>/...
• General concepts -> concepts/
• Recurring techniques/debug playbooks -> skills/
• Tools/services -> entities/
• Cross-session patterns -> synthesis/

For each impacted project, create/update projects/<name>/<name>.md (project name as filename, never _project.md).

Writing rules

• Distill knowledge, not chronology
• Avoid "on date X we discussed..." unless date context is essential
• Add summary: frontmatter on each new/updated page (1-2 sentences, <= 200 chars)
• Add confidence and lifecycle fields to every new page:

  base_confidence: 0.42
  lifecycle: draft
  lifecycle_changed: <ISO date today>
  

  Leave lifecycle unchanged on update.
• Add provenance markers:
  • ^[extracted] when directly grounded in explicit session content
  • ^[inferred] when synthesizing patterns across events/sessions
  • ^[ambiguous] when sessions conflict
• Add/update provenance: frontmatter mix for each changed page

Step 6: Update Manifest, Log, and Index

Update .manifest.json

For each processed source file:

• ingested_at, size_bytes, modified_at
• source_type: codex_rollout | codex_index | codex_history
• project: inferred project name (when applicable)
• pages_created, pages_updated

Add/update a top-level project/session summary block:

{
  "project-name": {
    "source_path": "~/.codex/sessions/...",
    "last_ingested": "TIMESTAMP",
    "sessions_ingested": 12,
    "sessions_total": 40,
    "index_updated_at": "TIMESTAMP"
  }
}

Update special files

Update index.md and log.md:

- [TIMESTAMP] CODEX_HISTORY_INGEST sessions=N pages_updated=X pages_created=Y mode=append|full

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Ingested 12 Codex sessions; surfaced recurring patterns in CLI tooling and shell scripting." Keep the last 3 operations. Update updated timestamp.

Privacy and Compliance

• Distill and synthesize; avoid raw transcript dumps
• Default to redaction for anything that looks sensitive
• Ask the user before storing personal/sensitive details
• Keep references to other people minimal and purpose-bound

Reference

See references/codex-data-format.md for field-level parsing notes and extraction guidance.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Daily Update — Wiki Maintenance Cycle

You run a lightweight maintenance pass over the wiki: check source freshness, refresh the index, update hot.md, and write the state file that the terminal notification reads.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and OBSIDIAN_WIKI_REPO.
2. Derive vault-scoped state dir — all runtime state is scoped to the resolved vault, not global:

   VAULT_ID=$(echo "$OBSIDIAN_VAULT_PATH" | md5sum 2>/dev/null | cut -c1-8 || md5 -q - <<< "$OBSIDIAN_VAULT_PATH" | cut -c1-8)
   STATE_DIR="$HOME/.obsidian-wiki/state/$VAULT_ID"
   mkdir -p "$STATE_DIR"
   

3. Read $OBSIDIAN_VAULT_PATH/.manifest.json.

Modes

Run Mode (default — triggered by cron or /daily-update)

Execute the maintenance cycle:

Step 1: Source freshness check

Compare each source in .manifest.json against its file's modification time. Classify as:

• Fresh — mtime ≤ ingested_at
• Stale — mtime > ingested_at (new content exists, not yet ingested)
• Missing — source file no longer exists

Step 2: Index refresh

Read $OBSIDIAN_VAULT_PATH/index.md. If any pages in the vault are missing from the index (or vice versa), update the index. Use find $OBSIDIAN_VAULT_PATH -name "*.md" -not -path "*/_*" to enumerate vault pages, then reconcile against the index.

Step 3: hot.md update

Read hot.md. If it's >48h old based on its updated: frontmatter, regenerate it: read the 10 most recently modified wiki pages and write a fresh ~500-word semantic snapshot of what the wiki covers. This keeps the next session's context warm without a full vault crawl.

Step 4: Write state

Write to the vault-scoped $STATE_DIR derived in "Before You Start":

date +%s > "$STATE_DIR/.last_update"
echo "<stale_count>" > "$STATE_DIR/.pending_delta"
echo "$OBSIDIAN_VAULT_PATH" > "$STATE_DIR/.vault_path"

Step 5: Spawn impl-validator

After the cycle, spawn impl-validator as a subagent:

impl-validator check:
  goal: "Daily wiki maintenance — index reconciled, hot.md refreshed, state file written"
  artifacts:
    - $OBSIDIAN_VAULT_PATH/index.md
    - $OBSIDIAN_VAULT_PATH/hot.md
    - $STATE_DIR/.last_update
    - $STATE_DIR/.pending_delta
  checks:
    - Does .last_update contain a recent Unix timestamp (within the last 60 seconds)?
    - Does .pending_delta contain a non-negative integer?
    - Does hot.md have an updated: frontmatter field set to today?
    - Does index.md list at least as many pages as exist in the vault?

Apply any FAILs before logging.

Step 6: Log

Append to $OBSIDIAN_VAULT_PATH/log.md:

- [TIMESTAMP] DAILY-UPDATE fresh=N stale=N missing=N index_added=N hot_refreshed=true|false

Step 7: Report to user

## Daily Wiki Update

- Sources: N fresh · N stale · N missing
- Index: N pages (N added, N removed)
- hot.md: refreshed / up to date

Stale sources (run to sync):
  /wiki-history-ingest claude   — N sessions since last ingest
  /wiki-history-ingest codex    — N sessions since last ingest

Setup Mode (triggered by "set up the daily cron" or "install terminal notification")

Walk the user through first-time setup:

Step 1: Verify script exists

Check that $OBSIDIAN_WIKI_REPO/scripts/daily-update.sh exists and is executable. If not, point the user to it.

Step 2: Install launchd plist

# Replace placeholder in plist
sed "s|OBSIDIAN_WIKI_REPO|$OBSIDIAN_WIKI_REPO|g" \
  "$OBSIDIAN_WIKI_REPO/scripts/com.obsidian-wiki.daily-update.plist" \
  > "$HOME/Library/LaunchAgents/com.obsidian-wiki.daily-update.plist"

# Load it
launchctl load "$HOME/Library/LaunchAgents/com.obsidian-wiki.daily-update.plist"

Step 3: Install terminal notification (optional)

Ask the user: "Do you want a terminal reminder when your wiki is stale? (y/n)" — skip this step if they say no, or if the environment is headless/VPS.

If yes, detect the user's shell and target the right rc file:

SHELL_NAME=$(basename "$SHELL")   # zsh, bash, fish, etc.
case "$SHELL_NAME" in
  zsh)  RC_FILE="$HOME/.zshrc" ;;
  bash) RC_FILE="$HOME/.bashrc" ;;
  *)    echo "Shell '$SHELL_NAME' not auto-detected. Add the source line manually to your shell rc file." ; return ;;
esac

Check if wiki-notify.sh is already sourced in that rc file. If not, append:

echo "" >> "$RC_FILE"
echo "# obsidian-wiki terminal notification" >> "$RC_FILE"
echo "source $OBSIDIAN_WIKI_REPO/scripts/wiki-notify.sh" >> "$RC_FILE"

For Fish shell, source syntax is different — provide the manual instruction:

# Add to ~/.config/fish/config.fish:
bass source $OBSIDIAN_WIKI_REPO/scripts/wiki-notify.sh
# (requires bass plugin, or copy the logic natively)

Step 4: Run the script once

bash "$OBSIDIAN_WIKI_REPO/scripts/daily-update.sh"

This initializes $STATE_DIR/.last_update so the terminal notification works immediately.

Step 5: Confirm

Tell the user:

• The cron runs daily at 9 AM (or on next login if missed)
• Terminal notifications appear when the wiki is >20 hours stale
• State is stored in ~/.obsidian-wiki/state/<vault-id>/ — supports multiple vaults independently
• They can run /daily-update anytime to force a sync
• Logs go to /tmp/obsidian-wiki-daily.log

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Hermes History Ingest — Conversation & Memory Mining

You are extracting knowledge from the user's Hermes agent history and distilling it into the Obsidian wiki. Hermes stores both free-form memories and structured session transcripts — focus on durable knowledge, not operational telemetry.

This skill can be invoked directly or via the wiki-history-ingest router (/wiki-history-ingest hermes).

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and HERMES_HISTORY_PATH (defaults to ~/.hermes)
2. Read .manifest.json at the vault root to check what has already been ingested
3. Read index.md at the vault root to understand what the wiki already contains

Ingest Modes

Append Mode (default)

Check .manifest.json for each source file. Only process:

• Files not in the manifest (new memory files, new session logs)
• Files whose modification time is newer than ingested_at in the manifest

Use this mode for regular syncs.

Full Mode

Process everything regardless of manifest. Use after wiki-rebuild or if the user explicitly asks for a full re-ingest.

Hermes Data Layout

Hermes stores all local artifacts under ~/.hermes/ (or $HERMES_HOME for non-default profiles).

~/.hermes/
├── memories/                          # Persistent agent memories (markdown or JSON)
│   └── *.md / *.json
├── skills/                            # Installed skills (read-only for ingest purposes)
│   └── <skill-name>/SKILL.md
├── sessions/                          # Session transcripts (if session logging is enabled)
│   └── YYYY-MM-DD/
│       └── <session-id>.jsonl
├── config.yaml                        # User config (model, theme, paths)
└── .hub/                              # Skills Hub state (lock.json, audit.log, quarantine/)

Key data sources ranked by value

1. memories/*.md / memories/*.json — highest signal; curated persistent knowledge the agent accumulated
2. sessions/**/*.jsonl — structured turn-by-turn transcripts; rich but noisy
3. config.yaml — metadata only (model preferences, paths); rarely worth ingesting

Skip .hub/ internals (audit/quarantine state) and the skills/ directory (source material, not user knowledge).

Step 1: Survey and Compute Delta

Scan HERMES_HISTORY_PATH and compare against .manifest.json:

• ~/.hermes/memories/
• ~/.hermes/sessions/**/ (if present)

Classify each file:

• New — not in manifest
• Modified — in manifest but file is newer than ingested_at
• Unchanged — already ingested and unchanged

Report a concise delta summary before deep parsing.

Step 2: Parse Memories First

Memories are the highest-value source. Hermes writes them as either:

• Markdown — structured prose with optional frontmatter; ingest directly
• JSON — {"content": "...", "created_at": "...", "tags": [...]} records

For each memory:

• Extract the core knowledge claim
• Note any tags Hermes attached (they often map to wiki categories)
• Merge into the appropriate wiki page rather than creating one memory = one page

Step 3: Parse Session JSONL Safely

Each session JSONL line is an event envelope. Common shapes:

{"role": "user", "content": "..."}
{"role": "assistant", "content": "..."}
{"type": "tool_use", "name": "...", "input": {...}}
{"type": "tool_result", "content": "..."}

Extraction rules

• Prioritize assistant responses that state conclusions, patterns, or decisions
• Extract user intent from high-signal turns; skip low-information follow-ups
• Treat tool_use / tool_result pairs as context, not primary content
• Skip token accounting, internal plumbing, and repeated plan echoes

Critical privacy filter

Session logs can include injected instructions, tool payloads, and sensitive text. Do not ingest verbatim.

• Remove API keys, tokens, passwords, credentials
• Redact private identifiers unless relevant and user-approved
• Summarize; do not quote raw transcripts verbatim

Step 4: Cluster by Topic

Do not create one wiki page per memory or session.

• Group memories by stable topic (concept, tool, project, technique)
• Split mixed sessions into separate themes
• Merge recurring patterns across dates and projects
• Use file paths or session cwd metadata to infer project scope when available

Step 5: Distill into Wiki Pages

Route extracted knowledge using existing wiki conventions:

• Project-specific architecture/process → projects/<name>/...
• General concepts → concepts/
• Recurring techniques/debug playbooks → skills/
• Tools/services/frameworks → entities/
• Cross-session patterns → synthesis/

For each impacted project, create/update projects/<name>/<name>.md.

Writing rules

• Distill knowledge, not chronology
• Avoid "on date X we discussed..." unless date context is essential
• Add summary: frontmatter on each new/updated page (1–2 sentences, ≤ 200 chars)
• Add confidence and lifecycle fields to every new page:

  base_confidence: 0.42
  lifecycle: draft
  lifecycle_changed: <ISO date today>
  

  Leave lifecycle unchanged on update.
• Add provenance markers:
  • ^[extracted] when directly grounded in explicit memory/session content
  • ^[inferred] when synthesizing patterns across multiple memories
  • ^[ambiguous] when memories conflict
• Add/update provenance: frontmatter mix for each changed page

Step 6: Update Manifest, Log, and Index

Update .manifest.json

For each processed source file:

• ingested_at, size_bytes, modified_at
• source_type: hermes_memory | hermes_session
• project: inferred project name (when applicable)
• pages_created, pages_updated

Add/update a top-level summary block:

{
  "hermes": {
    "source_path": "~/.hermes/",
    "last_ingested": "TIMESTAMP",
    "memories_ingested": 42,
    "sessions_ingested": 7,
    "pages_created": 5,
    "pages_updated": 12
  }
}

Update special files

Update index.md and log.md:

- [TIMESTAMP] HERMES_HISTORY_INGEST memories=N sessions=M pages_updated=X pages_created=Y mode=append|full

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Ingested 42 Hermes memories and 7 sessions; dominant themes: reasoning strategies, tool use patterns." Keep the last 3 operations. Update updated timestamp.

Privacy and Compliance

• Distill and synthesize; avoid raw memory or transcript dumps
• Default to redaction for anything that looks sensitive
• Ask the user before storing personal or sensitive details
• Keep references to other people minimal and purpose-bound

Reference

See references/hermes-data-format.md for field-level notes and extraction guidance.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

OpenClaw History Ingest — Session & Memory Mining

You are extracting knowledge from the user's OpenClaw agent history and distilling it into the Obsidian wiki. OpenClaw stores both a structured long-term MEMORY.md and per-session JSONL transcripts — focus on durable knowledge, not operational telemetry.

This skill can be invoked directly or via the wiki-history-ingest router (/wiki-history-ingest openclaw).

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and OPENCLAW_HISTORY_PATH (defaults to ~/.openclaw)
2. Read .manifest.json at the vault root to check what has already been ingested
3. Read index.md at the vault root to understand what the wiki already contains

Ingest Modes

Append Mode (default)

Check .manifest.json for each source file. Only process:

• Files not in the manifest (new session logs, updated MEMORY.md or daily notes)
• Files whose modification time is newer than ingested_at in the manifest

Use this mode for regular syncs.

Full Mode

Process everything regardless of manifest. Use after wiki-rebuild or if the user explicitly asks for a full re-ingest.

OpenClaw Data Layout

OpenClaw stores all local artifacts under ~/.openclaw/.

~/.openclaw/
├── openclaw.json                          # Global config
├── credentials/                           # Auth tokens (skip entirely)
├── workspace/                             # Agent workspace
│   ├── MEMORY.md                          # Long-term memory (loaded every session)
│   ├── DREAMS.md                          # Optional dream diary / summaries
│   └── memory/
│       ├── YYYY-MM-DD.md                  # Daily notes (today + yesterday auto-loaded)
│       └── ...
└── agents/
    └── <agentId>/
        ├── agent/
        │   └── models.json                # Agent config (skip)
        └── sessions/
            ├── sessions.json              # Session index
            └── <sessionId>.jsonl          # Session transcript (JSONL, append-only)

Key data sources ranked by value

1. workspace/MEMORY.md — highest signal; long-term durable facts the agent accumulated
2. workspace/memory/YYYY-MM-DD.md — daily notes; recent entries often contain active project context
3. agents/*/sessions/<id>.jsonl — session transcripts; rich but noisy
4. agents/*/sessions/sessions.json — session index for inventory and timestamps
5. workspace/DREAMS.md — optional summaries; ingest if present

Skip credentials/ entirely. Skip agents/*/agent/models.json (runtime config, not user knowledge).

Step 1: Survey and Compute Delta

Scan OPENCLAW_HISTORY_PATH and compare against .manifest.json:

• ~/.openclaw/workspace/MEMORY.md
• ~/.openclaw/workspace/DREAMS.md (if present)
• ~/.openclaw/workspace/memory/*.md
• ~/.openclaw/agents/*/sessions/sessions.json
• ~/.openclaw/agents/*/sessions/*.jsonl

Classify each file:

• New — not in manifest
• Modified — in manifest but file is newer than ingested_at
• Unchanged — already ingested and unchanged

Report a concise delta summary before deep parsing.

Step 2: Parse MEMORY.md First

MEMORY.md is the highest-value source. It is plain markdown, human-readable and human-editable. It typically contains:

• Durable facts about the user's preferences, environment, and recurring patterns
• Decisions and context the agent was told to remember
• Project-specific notes the agent accumulated over many sessions

Read it in full and extract concept-level knowledge. Do not create one wiki page per MEMORY.md entry — cluster by topic.

Step 3: Parse Daily Notes

workspace/memory/YYYY-MM-DD.md files contain time-stamped notes from that day's sessions. Prioritize recent files (last 30–90 days). Extract:

• Active project context and decisions made
• Patterns or techniques discovered
• Recurring blockers or solved problems

Older daily notes have diminishing signal — summarize in bulk rather than extracting line-by-line.

Step 4: Parse Session JSONL Safely

Each session file is JSONL (append-only, one JSON object per line):

{"role": "user",      "content": "...", "timestamp": "..."}
{"role": "assistant", "content": "...", "timestamp": "..."}
{"role": "tool",      "name": "...",   "content": "...", "timestamp": "..."}

Extraction rules

• Prioritize assistant turns that state conclusions, decisions, or patterns
• Extract user intent from high-signal turns; skip low-information follow-ups
• Tool calls are context, not primary knowledge — only extract if the result contains a reusable insight
• Cross-reference sessions.json index to get session names/labels before opening individual transcripts

Critical privacy filter

Session transcripts can include injected instructions, tool payloads, and sensitive text. Do not ingest verbatim.

• Remove API keys, tokens, passwords, credentials
• Redact private identifiers unless relevant and user-approved
• Summarize; do not quote raw transcripts verbatim

Step 5: Cluster by Topic

Do not create one wiki page per session or per MEMORY.md entry.

• Group by stable topic (concept, tool, project, technique)
• Split mixed sessions into separate themes
• Merge recurring patterns across dates and agents
• Use session cwd or workspace path to infer project scope when available

Step 6: Distill into Wiki Pages

Route extracted knowledge using existing wiki conventions:

• Project-specific architecture/process → projects/<name>/...
• General concepts → concepts/
• Recurring techniques/debug playbooks → skills/
• Tools/services/frameworks → entities/
• Cross-session patterns → synthesis/

For each impacted project, create/update projects/<name>/<name>.md.

Writing rules

• Distill knowledge, not chronology
• Avoid "on date X we discussed..." unless date context is essential
• Add summary: frontmatter on each new/updated page (1–2 sentences, ≤ 200 chars)
• Add confidence and lifecycle fields to every new page:

  base_confidence: 0.42
  lifecycle: draft
  lifecycle_changed: <ISO date today>
  

  Leave lifecycle unchanged on update.
• Add provenance markers:
  • ^[extracted] when directly grounded in explicit session/memory content
  • ^[inferred] when synthesizing patterns across multiple sessions
  • ^[ambiguous] when sessions conflict
• Add/update provenance: frontmatter mix for each changed page

Step 7: Update Manifest, Log, and Index

Update .manifest.json

For each processed source file:

• ingested_at, size_bytes, modified_at
• source_type: openclaw_memory | openclaw_daily_note | openclaw_session | openclaw_dreams
• agent_id: agent directory name (when applicable)
• pages_created, pages_updated

Add/update a top-level summary block:

{
  "openclaw": {
    "source_path": "~/.openclaw/",
    "last_ingested": "TIMESTAMP",
    "memory_updated_at": "TIMESTAMP",
    "daily_notes_ingested": 14,
    "sessions_ingested": 23,
    "pages_created": 6,
    "pages_updated": 18
  }
}

Update special files

Update index.md and log.md:

- [TIMESTAMP] OPENCLAW_HISTORY_INGEST memory=updated daily_notes=N sessions=M pages_updated=X pages_created=Y mode=append|full

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Ingested OpenClaw MEMORY.md and 14 daily notes; surfaced automation patterns and multi-agent coordination knowledge." Keep the last 3 operations. Update updated timestamp.

Privacy and Compliance

• Distill and synthesize; avoid raw memory or transcript dumps
• Default to redaction for anything that looks sensitive
• Ask the user before storing personal or sensitive details
• Keep references to other people minimal and purpose-bound

Reference

See references/openclaw-data-format.md for field-level notes and parsing guidance.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Pi History Ingest — Session Mining

You are extracting knowledge from the user's Pi coding agent sessions and distilling it into the Obsidian wiki. Pi sessions are stored as structured JSONL with a tree layout — your job is to follow the active branch, extract durable knowledge, and compile it.

Session knowledge closure: Pi session files are the only factual source for this skill. Do not add background knowledge from model training, other tools, package docs, local files, or the current conversation unless that fact appears in the selected session entries. If outside context seems useful, mark it as an open question or skip it — never present it as extracted session knowledge.

This skill can be invoked directly or via the wiki-history-ingest router (/wiki-history-ingest pi).

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and PI_HISTORY_PATH (defaults to ~/.pi/agent/sessions)
2. Read .manifest.json at the vault root to check what has already been ingested
3. Read index.md at the vault root to understand what the wiki already contains

Ingest Modes

Append Mode (default)

Check .manifest.json for each source file. Only process:

• Files not in the manifest (new sessions)
• Files whose modification time is newer than ingested_at in the manifest

Use this mode for regular syncs.

Full Mode

Process everything regardless of manifest. Use after wiki-rebuild or if the user explicitly asks for a full re-ingest.

Pi Data Layout

Pi stores sessions under ~/.pi/agent/sessions/ (or the path set by PI_CODING_AGENT_SESSION_DIR).

~/.pi/agent/sessions/
├── --<cwd-path>--/                    # Working directory with / replaced by -
│   └── <timestamp>_<uuid>.jsonl       # Session JSONL file
└── ...

The session filename contains an ISO timestamp and UUID. The parent directory encodes the working directory where the session was created.

Session JSONL Format

Each .jsonl file is a sequence of JSON objects. The first line is always a session header; subsequent lines are tree entries with id and parentId.

Key entry types:

Message roles inside message entries

• user — user input; content is string or (TextContent \| ImageContent)[]
• assistant — assistant response; content is (TextContent \| ThinkingContent \| ToolCall)[]
• toolResult — tool execution result; content is (TextContent \| ImageContent)[]
• bashExecution — bash command + output; command, output, exitCode
• branchSummary — branch switch summary; summary string
• compactionSummary — compaction summary; summary string

Key data sources ranked by value

1. message entries (user + assistant) — full conversation transcripts; rich but noisy
2. compaction entries — pre-synthesized summaries of older context; gold
3. branch_summary entries — summaries of abandoned branches; good signal
4. bashExecution entries — concrete commands run; useful for workflow patterns
5. session_info entries — session name for topic inference

Skip model_change, thinking_level_change, custom (extension state), and label entries.

Step 1: Survey and Compute Delta

Scan PI_HISTORY_PATH and compare against .manifest.json:

# List all session files
find ~/.pi/agent/sessions -name "*.jsonl" -type f

# Or with custom path
find "$PI_HISTORY_PATH" -name "*.jsonl" -type f

Build an inventory. For each session file, record:

• path — absolute path
• cwd — decoded from parent directory name (--<path>-- → /path)
• session_name — from the latest session_info entry (if any)
• modified_at — file mtime
• already_ingested — presence in .manifest.json

Classify each file:

• New — not in manifest
• Modified — in manifest but file is newer than ingested_at
• Unchanged — already ingested and unchanged

Report a concise delta summary before deep parsing:

"Found N Pi sessions across K projects. Delta: X new, Y modified."

Step 2: Parse Session JSONL

For each selected session file, read it line by line. Because sessions use a tree structure, build the active branch first:

1. Parse all entries into a map by id
2. Find the current leaf (the entry with no children, or the last message entry)
3. Walk parentId chain from leaf to root to get the active path
4. Reverse the path so it's chronological

Extraction rules

From the active path, extract:

• session header — cwd, timestamp, parentSession (if forked)
• session_info — name field for session title/topic inference
• message entries with role: "user" — extract content text (skip images)
• message entries with role: "assistant" — extract text content blocks; skip thinking blocks (noise); note toolCall blocks (they reveal what the agent actually did)
• message entries with role: "toolResult" — summarize outcomes, not full output
• message entries with role: "bashExecution" — extract command + exit code; recurring commands reveal build/test/deploy workflows
• compaction entries — read summary verbatim; it's already distilled
• branch_summary entries — read summary verbatim; captures abandoned approaches

Evidence ledger

As you parse, build a private evidence ledger before writing any wiki page. Each durable fact or decision you may write must carry at least one source reference:

pi:<session-file-basename>#<entry-id>

If an entry lacks an id, use pi:<session-file-basename>:line<N> from the JSONL line number. Keep the cited text snippet or summarized observation next to the reference while drafting so you can verify claims before writing.

Skip / noise filters

• thinking content blocks — internal reasoning, not durable knowledge
• Image content blocks — skip unless the user explicitly asks for image transcription
• Raw tool outputs longer than 500 chars — summarize the outcome
• Token accounting (usage fields) — metadata only
• Repeated plan echoes or status updates

Critical privacy filter

Session logs can include injected instructions, tool payloads, and sensitive text. Do not ingest verbatim.

• Remove API keys, tokens, passwords, credentials
• Redact private identifiers unless relevant and user-approved
• Summarize bash outputs that contain paths, environment variables, or secrets
• Do not quote raw toolCall arguments verbatim if they contain sensitive data

Step 3: Cluster by Topic

Do not create one wiki page per session.

• Group knowledge by stable topic across many sessions
• Split mixed sessions into separate themes
• Merge recurring patterns across dates and projects only when each pattern member has evidence ledger references
• Use the cwd from the session header to infer project scope
• Use session_info.name as a topic hint when available
• Drop any cluster whose key claims cannot be traced back to the selected session files

Step 4: Distill into Wiki Pages

Route extracted knowledge using existing wiki conventions:

• Project-specific architecture/process → projects/<name>/...
• General concepts → concepts/
• Recurring techniques/debug playbooks → skills/
• Tools/services/frameworks → entities/
• Cross-session patterns → synthesis/

For each impacted project, create/update projects/<name>/<name>.md.

Writing rules

• Distill knowledge, not chronology
• Avoid "on date X we discussed..." unless date context is essential
• Preserve session-specific decision context when it explains why an approach was chosen; do not flatten it into generic tool advice.
• Add summary: frontmatter on each new/updated page (1–2 sentences, ≤ 200 chars)
• Add confidence and lifecycle fields to every new page:

  base_confidence: 0.42
  lifecycle: draft
  lifecycle_changed: <ISO date today>
  

  Leave lifecycle unchanged on update.
• Add provenance markers using the convention in llm-wiki:
  • Extracted claims use no inline marker by default, but must have a nearby source reference comment.
  • ^[inferred] when synthesizing patterns across multiple sessions or inferring from tool calls.
  • ^[ambiguous] when sessions conflict or a compaction summary contradicts later turns.
• Add a source reference comment near every extracted paragraph or bullet:

  - Durable fact from the session. <!-- source: pi:2026-06-01T120000_abcd.jsonl#entry-123 -->
  

  Multiple sources are comma-separated. These comments are the audit trail; do not omit them for extracted claims.
• Add/update provenance: frontmatter mix for each changed page.

Mark provenance per the convention in llm-wiki:

• compaction and branch_summary entries are pre-distilled — treat as mostly extracted, with source reference comments.
• Conversation distillation is mostly ^[inferred] — you're synthesizing from dialogue, and it still needs source references to the turns that support the synthesis.
• Use ^[ambiguous] when the user changed their mind across sessions or when compaction summaries disagree with later conversation turns.

Source verification gate

Before writing any page, verify the draft against the evidence ledger:

1. Every claim (extracted / ^[inferred] / ^[ambiguous]) has at least one pi:... source reference; extracted claims must use a nearby <!-- source: pi:... --> comment.
2. Every source reference points to a selected session file and an entry on the active branch (or a cited compaction / branch_summary).
3. Proper nouns, tool names, command names, filenames, URLs, package names, and error strings in claims appear in the cited entry text or command fields. Use literal search (grep/rg) on the session file for distinctive strings when in doubt.
4. If a claim cannot be verified, either delete it or mark it ^[inferred] / ^[ambiguous] with the supporting source refs; never leave unverifiable content without one of these markers (unmarked implies extracted).
5. Do not write facts learned from the model's training data or the current agent session unless they are explicitly present in the Pi session evidence.

Step 5: Update Manifest, Log, and Index

Update .manifest.json

For each processed source file:

• ingested_at, size_bytes, modified_at
• source_type: pi_session
• project: inferred project name from decoded cwd
• pages_created, pages_updated

Add/update a top-level summary block:

{
  "pi": {
    "source_path": "~/.pi/agent/sessions/",
    "last_ingested": "TIMESTAMP",
    "sessions_ingested": 12,
    "sessions_total": 40,
    "pages_created": 5,
    "pages_updated": 12
  }
}

Update special files

Update index.md and log.md:

- [TIMESTAMP] PI_HISTORY_INGEST sessions=N pages_updated=X pages_created=Y mode=append|full

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Ingested 12 Pi sessions across 3 projects; surfaced patterns in CLI tooling and API design." Keep the last 3 operations. Update updated timestamp.

Privacy and Compliance

• Distill and synthesize; avoid raw transcript dumps
• Default to redaction for anything that looks sensitive
• Ask the user before storing personal or sensitive details
• Keep references to other people minimal and purpose-bound

Reference

See references/pi-data-format.md for field-level parsing notes and extraction guidance.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

• Decide what you want the skill to do and roughly how it should do it
• Write a draft of the skill
• Create a few test prompts and run claude-with-access-to-the-skill on them
• Help the user evaluate the results both qualitatively and quantitatively
  • While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
  • Use the eval-viewer/generate_review.py script to show the user the results for them to look at, and also let them look at the quantitative metrics
• Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
• Repeat until you're satisfied
• Expand the test set and try again at larger scale

Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.

On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.

Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.

Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.

Cool? Cool.

Communicating with the user

The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.

So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:

• "evaluation" and "benchmark" are borderline, but OK
• for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them

It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.

Creating a skill

Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.

Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.

Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.

Write the SKILL.md

Based on the user interview, fill in these components:

• name: Skill identifier
• description: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
• compatibility: Required tools, dependencies (optional, rarely needed)
• the rest of the skill :)

Skill Writing Guide

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

Progressive Disclosure

Skills use a three-level loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - In context whenever skill triggers (<500 lines ideal)
3. Bundled resources - As needed (unlimited, scripts can execute without loading)

These word counts are approximate and you can feel free to go longer if needed.

Key patterns:

• Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
• Reference files clearly from SKILL.md with guidance on when to read them
• For large reference files (>300 lines), include a table of contents

Domain organization: When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude reads only the relevant reference file.

Principle of Lack of Surprise

This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.

Writing Patterns

Prefer using the imperative form in instructions.

Defining output formats - You can do it like this:

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Examples pattern - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Writing Style

Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.

Test Cases

After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.

Save test cases to evals/evals.json. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

See references/schemas.md for the full schema (including the assertions field, which you'll add later).

Running and evaluating test cases

This section is one continuous sequence — don't stop partway through. Do NOT use /skill-test or any other testing skill.

Put results in <skill-name>-workspace/ as a sibling to the skill directory. Within the workspace, organize results by iteration (iteration-1/, iteration-2/, etc.) and within that, each test case gets a directory (eval-0/, eval-1/, etc.). Don't create all of this upfront — just create directories as you go.

Step 1: Spawn all runs (with-skill AND baseline) in the same turn

For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.

With-skill run:

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

Baseline run (same prompt, but the baseline depends on context):

• Creating a new skill: no skill at all. Same prompt, no skill path, save to without_skill/outputs/.
• Improving an existing skill: the old version. Before editing, snapshot the skill (cp -r <skill-path> <workspace>/skill-snapshot/), then point the baseline subagent at the snapshot. Save to old_skill/outputs/.

Write an eval_metadata.json for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

Step 2: While runs are in progress, draft assertions

Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in evals/evals.json, review them and explain what they check.

Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.

Update the eval_metadata.json files and evals/evals.json with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.

Step 3: As runs complete, capture timing data

When each subagent task completes, you receive a notification containing total_tokens and duration_ms. Save this data immediately to timing.json in the run directory:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.

Step 4: Grade, aggregate, and launch the viewer

Once all runs are done:

1. Grade each run — spawn a grader subagent (or grade inline) that reads agents/grader.md and evaluates each assertion against the outputs. Save results to grading.json in each run directory. The grading.json expectations array must use the fields text, passed, and evidence (not name/met/details or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.

2. Aggregate into benchmark — run the aggregation script from the skill-creator directory:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   This produces benchmark.json and benchmark.md with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see references/schemas.md for the exact schema the viewer expects. Put each with_skill version before its baseline counterpart.

3. Do an analyst pass — read the benchmark data and surface patterns the aggregate stats might hide. See agents/analyzer.md (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.

4. Launch the viewer with both qualitative outputs and quantitative data:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   For iteration 2+, also pass --previous-workspace <workspace>/iteration-<N-1>.

   Cowork / headless environments: If webbrowser.open() is not available or the environment has no display, use --static <output_path> to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a feedback.json file when the user clicks "Submit All Reviews". After download, copy feedback.json into the workspace directory for the next iteration to pick up.

Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.

5. Tell the user something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."

What the user sees in the viewer

The "Outputs" tab shows one test case at a time:

• Prompt: the task that was given
• Output: the files the skill produced, rendered inline where possible
• Previous Output (iteration 2+): collapsed section showing last iteration's output
• Formal Grades (if grading was run): collapsed section showing assertion pass/fail
• Feedback: a textbox that auto-saves as they type
• Previous Feedback (iteration 2+): their comments from last time, shown below the textbox

The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.

Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to feedback.json.

Step 5: Read the feedback

When the user tells you they're done, read feedback.json:

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.

Kill the viewer server when you're done with it:

kill $VIEWER_PID 2>/dev/null

Improving the skill

This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.

How to think about improvements

1. Generalize from the feedback. The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.

2. Keep the prompt lean. Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.

3. Explain the why. Try hard to explain the why behind everything you're asking the model to do. Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.

4. Look for repeated work across test cases. Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a create_docx.py or a build_chart.py, that's a strong signal the skill should bundle that script. Write it once, put it in scripts/, and tell the skill to use it. This saves every future invocation from reinventing the wheel.

This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.

The iteration loop

After improving the skill:

1. Apply your improvements to the skill
2. Rerun all test cases into a new iteration-<N+1>/ directory, including baseline runs. If you're creating a new skill, the baseline is always without_skill (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
3. Launch the reviewer with --previous-workspace pointing at the previous iteration
4. Wait for the user to review and tell you they're done
5. Read the new feedback, improve again, repeat

Keep going until:

• The user says they're happy
• The feedback is all empty (everything looks good)
• You're not making meaningful progress

Advanced: Blind comparison

For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read agents/comparator.md and agents/analyzer.md for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.

This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.

Description Optimization

The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.

Step 1: Generate trigger eval queries

Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).

Bad: "Format this data", "Extract text from PDF", "Create a chart"

Good: "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

For the should-trigger queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.

For the should-not-trigger queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.

The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.

Step 2: Review with user

Present the eval set to the user for review using the HTML template:

1. Read the template from assets/eval_review.html
2. Replace the placeholders:
   • __EVAL_DATA_PLACEHOLDER__ → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
   • __SKILL_NAME_PLACEHOLDER__ → the skill's name
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → the skill's current description
3. Write to a temp file (e.g., /tmp/eval_review_<skill-name>.html) and open it: open /tmp/eval_review_<skill-name>.html
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
5. The file downloads to ~/Downloads/eval_set.json — check the Downloads folder for the most recent version in case there are multiple (e.g., eval_set (1).json)

This step matters — bad eval queries lead to bad descriptions.

Step 3: Run the optimization loop

Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."

Save the eval set to the workspace, then run in the background:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.

While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.

This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with best_description — selected by test score rather than train score to avoid overfitting.

How skill triggering works

Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's available_skills list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.

This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.

Step 4: Apply the result

Take best_description from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.

Package and Present (only if present_files tool is available)

Check whether you have access to the present_files tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:

python -m scripts.package_skill <path/to/skill-folder>

After packaging, direct the user to the resulting .skill file path so they can install it.

Claude.ai-specific instructions

In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:

Running test cases: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.

Reviewing results: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"

Benchmarking: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.

The iteration loop: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.

Description optimization: This section requires the claude CLI tool (specifically claude -p) which is only available in Claude Code. Skip it if you're on Claude.ai.

Blind comparison: Requires subagents. Skip it.

Packaging: The package_skill.py script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting .skill file.

Updating an existing skill: The user might be asking you to update an existing skill, not create a new one. In this case:

• Preserve the original name. Note the skill's directory name and name frontmatter field -- use them unchanged. E.g., if the installed skill is research-helper, output research-helper.skill (not research-helper-v2).
• Copy to a writeable location before editing. The installed skill path may be read-only. Copy to /tmp/skill-name/, edit there, and package from the copy.
• If packaging manually, stage in /tmp/ first, then copy to the output directory -- direct writes may fail due to permissions.

Cowork-Specific Instructions

If you're in Cowork, the main things to know are:

• You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
• You don't have a browser or display, so when generating the eval viewer, use --static <output_path> to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
• For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using generate_review.py (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself. You want to get them in front of the human ASAP!
• Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download feedback.json as a file. You can then read it from there (you may have to request access first).
• Packaging works — package_skill.py just needs Python and a filesystem.
• Description optimization (run_loop.py / run_eval.py) should work in Cowork just fine since it uses claude -p via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
• Updating an existing skill: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.

Reference files

The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.

• agents/grader.md — How to evaluate assertions against outputs
• agents/comparator.md — How to do blind A/B comparison between two outputs
• agents/analyzer.md — How to analyze why one version beat another

The references/ directory has additional documentation:

• references/schemas.md — JSON structures for evals.json, grading.json, etc.

Repeating one more time the core loop here for emphasis:

• Figure out what the skill is about
• Draft or edit the skill
• Run claude-with-access-to-the-skill on test prompts
• With the user, evaluate the outputs:
  • Create benchmark.json and run eval-viewer/generate_review.py to help the user review them
  • Run quantitative evals
• Repeat until you and the user are satisfied
• Package the final skill and return it to the user.

Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run eval-viewer/generate_review.py so human can review test cases" in your TodoList to make sure it happens.

Good luck!

Wiki Context Pack — Bounded Token Retrieval

You are producing a focused, token-bounded context pack from the wiki. Unlike wiki-query (which answers a question), this skill packages the most relevant wiki knowledge into a single markdown block that a downstream agent, skill, or user can consume directly.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and any QMD variables.
2. Read $OBSIDIAN_VAULT_PATH/hot.md if it exists — gives instant context on recent activity.
3. Read $OBSIDIAN_VAULT_PATH/index.md — the full page inventory.

Invocation Forms

/wiki-context-pack "transformer attention mechanism" --budget 16000
/wiki-context-pack "my-project architecture decisions" --budget 8000
/wiki-context-pack --recent --budget 4000   # recent activity pack from hot.md
/wiki-context-pack "authentication patterns"          # default budget: 8000 tokens

Parse the user's invocation to extract:

• topic — the query string (required unless --recent)
• --budget N — token budget in tokens (default: 8000; max: 100000)
• --recent — pack the most recently updated/ingested pages instead of a topic query

Algorithm

Step 1: Relevance Pass (cheap)

Without opening page bodies:

1. Scan index.md and frontmatter for topic match. Score each page:

   • +5 exact title or alias match
   • +3 tag match
   • +2 summary: field contains the query term
   • +1 index.md entry description contains the query term

2. For --recent mode: sort pages by updated: frontmatter descending. Take top 20 as candidates.

3. For topic mode: collect the top 20 candidates by score. If QMD is configured (QMD_WIKI_COLLECTION set), run a semantic pass and merge with the frontmatter score (QMD rank adds +4 to the page's score).

Step 2: Tier-Aware Selection

Within the candidate set, sort by relevance score, then apply tier ordering within each score bucket (see llm-wiki/SKILL.md, Importance Tiering section):

1. All core-tier matches first
2. Then supporting
3. Then peripheral (only if budget allows)

Maintain this ordering when filling the budget in Step 3.

Step 3: Compression

For each selected page (in tier/relevance order), compute its compressed representation — not a full read, but a structured distillation:

1. Required: title, tier:, tags:, summary: (from frontmatter — cheap, no body read needed)
2. If budget allows: add the page body, but stripped of:
   • Frontmatter block (already captured above)
   • The ## Sources section (keep source names in a one-liner instead)
   • Duplicate wikilinks that are already mentioned in included pages
   • Boilerplate headers with no content following them
3. Dedup overlapping content — if two selected pages share a paragraph (or near-identical claim), keep it only in the more relevant page. Mark the removal: _(content also in [[other-page]])_.

Estimate tokens for each page representation as len(text_chars) / 4.

Step 4: Budget Enforcement

Fill the pack greedily in tier/relevance order until the budget is exhausted:

1. Always include the frontmatter summary block for every selected page, even if the body doesn't fit.
2. If a page body doesn't fit in full, include a compressed excerpt: the first non-header paragraph plus the "Key Ideas" section (if present).
3. Drop peripheral-tier pages first when trimming.
4. Keep a running token count. Stop adding pages when the next page would exceed the budget.
5. Track how many pages were dropped and note it in the header.

Step 5: Render Output

Emit a single markdown block:

# Context Pack: <topic>
# Generated: <ISO timestamp>
# Budget: <budget> tokens | Actual: <actual> tokens | Pages: <N included> / <M candidates>
# Methodology: 4 chars/token estimate

---

## [[<category/page-name>]] (<tier>, ~<tokens> tokens)
tags: #tag1 #tag2
summary: <summary field text>

<compressed body or excerpt>

---

## [[<next-page>]] (<tier>, ~<tokens> tokens)
...

If --recent mode, the header reads:

# Context Pack: Recent Activity (last N pages)

Empty result: If no pages scored above 0 and --recent produced no results, output:

# Context Pack: <topic>
No relevant pages found. Consider running /wiki-ingest to add sources about this topic.

Step 6: Log

Append to $OBSIDIAN_VAULT_PATH/log.md:

- [TIMESTAMP] CONTEXT_PACK topic="<topic>" budget=<N> actual_tokens=<M> pages_included=<K> pages_dropped=<D>

Use Cases

• Feed into /wiki-research — pass the pack as context to avoid re-discovering known facts
• Pass to /wiki-synthesize — scoped input for a specific synthesis task
• Provide to external agents via MCP or clipboard — bounded, structured, citation-ready
• Checkpoint context before a long multi-step task — know what the wiki already knows before starting

Notes

• The 4 chars/token heuristic matches wiki-status's token footprint estimate — consistent across skills
• The pack is a snapshot; it is not written to the vault. Re-run to refresh.
• For very large budgets (> 50K tokens), warn the user: "This pack is large. Consider narrowing your topic or using wiki-query for a targeted answer instead."

Wiki Dashboard — Dynamic Vault Views

Two tools available: Obsidian Bases (native, GUI-driven, no plugin) and Dataview (community plugin, SQL-like, more powerful). Check which the user has and prefer Bases unless they ask for Dataview or need GROUP BY / computed columns.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH.
2. Read $OBSIDIAN_VAULT_PATH/index.md to understand what categories and pages exist.
3. Ask the user what they want to view if not specified — folder, tag, category, date range?
4. Ask if they have Dataview installed if you're unsure which tool to use.

Option A — Obsidian Bases (.base files)

Bases are YAML files that define live views over vault notes. Native to Obsidian 1.8+, no plugin needed.

Official canonical schema

Top-level keys:

filters:      # Global filter applied to all views (expression strings under and/or/not)
formulas:     # Named computed properties — referenced as formula.<name>
properties:   # Display config per property — sets displayName for column headers
summaries:    # Aggregation formulas (e.g. mean, sum)
views:        # Array of view definitions (required)

Each item in views::

views:
  - type: table          # table | list | cards | map
    name: "View Name"    # display label
    limit: 50            # optional max rows
    order:               # column display order (list of property/formula names)
      - file.name
      - note.updated
    groupBy:             # grouping — goes INSIDE the view, NOT at top level
      property: note.tags
      direction: ASC     # ASC | DESC
    filters:             # view-specific filter (merges with global filters)
      and:
        - 'note.status != "done"'
    summaries:
      formula.myFormula: Average

Filter syntax — CRITICAL

Filters use expression strings, not typed objects. Always wrap in and:, or:, or not: — a bare list causes a "may only have one of and/or/not keys" parse error.

# CORRECT
filters:
  and:
    - file.inFolder("concepts")

# WRONG — typed objects (parse error)
filters:
  - type: folder
    folder: concepts

Filters support nesting:

filters:
  or:
    - file.hasTag("book")
    - and:
        - file.inFolder("concepts")
        - file.hasTag("research")
    - not:
        - file.hasTag("archived")

Property name conventions

Different contexts use different naming — confirmed from Obsidian's auto-reformat behaviour:

Basic table — folder filter

filters:
  and:
    - file.inFolder("concepts")
properties:
  file.name:
    displayName: Page
  note.tags:
    displayName: Tags
  note.summary:
    displayName: Summary
  note.updated:
    displayName: Updated
views:
  - type: table
    name: Table
    order:
      - file.name
      - tags
      - summary
      - updated

Cards view — folder filter

filters:
  and:
    - file.inFolder("entities")
properties:
  file.name:
    displayName: Entity
  note.title:
    displayName: Full Name
  note.tags:
    displayName: Tags
  note.summary:
    displayName: Summary
views:
  - type: cards
    name: Cards
    order:
      - file.name
      - title
      - tags
      - summary

Group by property — groupBy goes INSIDE the view

When groupBy is set, omit that property from order: — it becomes the group header row and adding it as a column too causes duplication.

filters:
  and:
    - file.inFolder("concepts")
properties:
  file.name:
    displayName: Concept
  note.summary:
    displayName: Summary
  note.updated:
    displayName: Updated
views:
  - type: table
    name: By Domain
    groupBy:
      property: tags        # bare property name, no note. prefix
      direction: ASC
    order:
      - file.name           # do NOT include tags here — already the group header
      - summary
      - updated

Tag filter

filters:
  and:
    - file.hasTag("machine-learning")
properties:
  file.name:
    displayName: Page
  note.category:
    displayName: Category
  note.summary:
    displayName: Summary
views:
  - type: table
    name: Table
    order:
      - file.name
      - category
      - summary

Multi-filter (folder AND tag)

filters:
  and:
    - file.inFolder("projects")
    - file.hasTag("active")
properties:
  file.name:
    displayName: Project
  note.summary:
    displayName: Summary
  note.updated:
    displayName: Last Updated
views:
  - type: cards
    name: Cards
    order:
      - file.name
      - summary
      - updated

OR filter (two folders)

filters:
  or:
    - file.inFolder("concepts")
    - file.inFolder("entities")
properties:
  file.name:
    displayName: Page
  note.category:
    displayName: Category
  note.updated:
    displayName: Updated
views:
  - type: table
    name: Table
    order:
      - file.name
      - category
      - updated

Computed column via formulas

filters:
  and:
    - file.inFolder("concepts")
formulas:
  days_stale: "floor((now() - note.updated) / 86400000)"
properties:
  file.name:
    displayName: Page
  note.updated:
    displayName: Updated
  formula.days_stale:
    displayName: Days Stale
views:
  - type: table
    name: Stale
    order:
      - file.name
      - updated
      - formula.days_stale

Filter expression reference

On Obsidian UI-generated format: When Obsidian's GUI writes or reformats a .base file it may output a simplified shorthand with top-level columns:, sort:, and view: keys instead of the canonical schema. That format also works — Obsidian accepts both. Manually authored files should use the canonical schema above.

Option B — Dataview (community plugin)

Dataview uses a SQL-like query language inside ```dataview ``` code blocks in any note. More powerful than Bases for computed columns, GROUP BY, and cross-folder queries.

Basic table — folder

```dataview
TABLE
  tags AS "Tags",
  summary AS "Summary",
  file.mtime AS "Last Modified"
FROM "concepts"
SORT file.mtime DESC
```

Table with clickable links (TABLE WITHOUT ID)

```dataview
TABLE WITHOUT ID
  file.link AS "Entity",
  tags AS "Tags",
  summary AS "Summary"
FROM "entities"
SORT file.name ASC
```

GROUP BY — use rows. prefix after grouping

After GROUP BY, individual file properties must be prefixed with rows. — otherwise the column is empty or errors.

```dataview
TABLE WITHOUT ID
  rows.file.link AS "Concept",
  rows.summary AS "Summary"
FROM "concepts"
GROUP BY tags[0] AS "Domain"
```

Stale pages — use file.mtime for date math

Avoid choice(updated, date(updated), file.mtime) — mixed date formats in updated frontmatter cause arithmetic errors. file.mtime is always a valid DateTime.

```dataview
TABLE WITHOUT ID
  file.link AS "Page",
  category AS "Type",
  file.mtime AS "Last Modified",
  (date(today) - file.mtime).days + " days" AS "Age"
FROM "concepts" OR "entities" OR "projects"
WHERE file.name != file.folder
WHERE (date(today) - file.mtime).days > 30
SORT (date(today) - file.mtime).days DESC
```

Multi-folder query

```dataview
TABLE
  summary AS "Summary",
  file.mtime AS "Last Modified"
FROM "projects"
WHERE file.name != file.folder
SORT file.mtime DESC
```

Dataview reference

Step 3: Write the File

Bases: Target path $OBSIDIAN_VAULT_PATH/_meta/<dashboard-name>.base

Dataview: Write queries directly into any .md note. A dedicated dashboard note at $OBSIDIAN_VAULT_PATH/_meta/dashboard.md works well for multi-section views.

Slug examples:

• "All concepts" → _meta/concepts-index.base
• "Recent ingests" → _meta/recent-ingests.base
• "Project overview" → _meta/projects-overview.base
• "Stale pages" → _meta/stale-pages.base
• "Full dashboard" → _meta/dashboard.md

Create _meta/ if it doesn't exist yet.

Step 4: Embed Bases (optional)

To embed a .base inside a note:

## Entities
![[_meta/entities-tracker.base]]

Ask before modifying an existing note.

Step 5: Update Tracking

Append to $OBSIDIAN_VAULT_PATH/log.md:

- [TIMESTAMP] WIKI_DASHBOARD name="<slug>" tool=bases|dataview view=<type> filter="<description>"

No manifest or index update needed — dashboards are live queries, not static pages.

Common Dashboard Recipes

Quality Checklist

• Bases: filters use expression strings under and:/or:/not:, never typed objects
• Bases: groupBy goes inside the view definition — not as a top-level key
• Bases: column headers set via properties: <name>: displayName: "...", not columns: [{title}]
• Bases: formulas: used for computed columns, referenced as formula.<name> in order/properties
• Dataview: GROUP BY queries use rows.property not bare property
• Dataview: date arithmetic uses file.mtime, not choice(updated, ...)
• File written to _meta/ with a descriptive slug
• log.md updated
• User told how to embed Bases (![[_meta/<name>.base]]) or open the dashboard note

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Unified History Ingest Router

This is a thin router for history sources only. It does not replace wiki-ingest for documents.

Subcommands

If the user invokes /wiki-history-ingest <target> (or equivalent text command), dispatch directly:

Routing Rules

1. If the user explicitly says claude, copilot, codex, hermes, openclaw, or pi, route directly.
2. If the user provides a path/source:
   • ~/.claude or Claude memory/session JSONL artifacts -> claude-history-ingest
   • ~/.copilot, session-store.db, VS Code copilot-chat transcripts -> copilot-history-ingest
   • ~/.codex or rollout/session index artifacts -> codex-history-ingest
   • ~/.hermes or Hermes memories/session artifacts -> hermes-history-ingest
   • ~/.openclaw or OpenClaw MEMORY.md/session JSONL artifacts -> openclaw-history-ingest
   • ~/.pi/agent/sessions or Pi session JSONL artifacts -> pi-history-ingest
3. If ambiguous, ask one short clarification:
   • "Should I ingest claude, copilot, codex, hermes, openclaw, or pi history?"

Execution Contract

• After routing, execute the destination skill's workflow exactly.
• Do not duplicate destination logic in this file.
• Leave manifest/index/log update semantics to the destination skill.

UX Convention

• Use wiki-ingest for documents/content sources
• Use wiki-history-ingest for agent history sources

Examples:

• /wiki-history-ingest claude
• /wiki-history-ingest copilot
• /wiki-history-ingest codex
• /wiki-history-ingest hermes
• /wiki-history-ingest openclaw
• /wiki-history-ingest pi
• $wiki-history-ingest claude (agents that use $skill invocation)
• $wiki-history-ingest copilot

Wiki Import — Reconstruct Pages from an Export

You are importing a vault's knowledge into the current vault from one of two sources produced by wiki-export:

• graph.json — the graph skeleton. Reconstructs page stubs (frontmatter, typed relationships, a ## Related link list — no body). Lossy.
• OKF bundle (a wiki-export/okf/ directory) — the actual markdown files. Reconstructs full pages with their real bodies. Lossless. Use this for true vault-to-vault transfer.

Either way, the import writes pages with correct frontmatter and wikilinks, then updates all vault metadata. Step 2, Step 3 (graph only), and Step 5 are shared; Step 4 forks by source type.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH.
2. Read $OBSIDIAN_VAULT_PATH/AGENTS.md if it exists — apply any owner-specific conventions.

Step 1: Locate and Detect Source Type

Find the import source:

• If the user provided a path argument, use it directly.
• Otherwise auto-detect, in order: ./wiki-export/okf/ (a directory) → ./wiki-export/graph.json (a file).
• If neither exists, ask the user for the path.

Detect the source type:

• The path is a file ending in .json → graph.json import (validate below, then Step 3 + Step 4-Graph).
• The path is a directory containing .md files with OKF frontmatter (a type: key), and/or a root index.md with okf_version → OKF bundle import (skip Step 3; go to Step 4-OKF).
• Anything else → report what's wrong and stop.

Validate a graph.json source:

• Must be valid JSON
• Must have top-level keys: nodes (array), links (array), graph (object)
• Must have at least 1 node

If validation fails, report what's wrong and stop.

Validate an OKF bundle source:

• Must contain at least 1 non-reserved .md file (i.e. not index.md/log.md) with parseable YAML frontmatter containing a non-empty type.
• A .md with no frontmatter or no type is skipped (with a count), not fatal — OKF consumers are permissive (OKF §9).

Show a preview before importing:

graph.json:

Import preview (graph.json — stubs)
  Source: <path>  (exported at <graph.exported_at>)
  Nodes:  N total  (concepts: A, entities: B, skills: C, references: D, ...)
  Links:  M edges  (X typed, Y untyped)
  Target: $OBSIDIAN_VAULT_PATH

OKF bundle:

Import preview (OKF bundle — full pages)
  Source: <dir>  (okf_version <ver if present>)
  Pages:  N total  (concepts: A, entities: B, skills: C, references: D, ...)
  Target: $OBSIDIAN_VAULT_PATH

Step 2: Determine Conflict Resolution Mode

Read the user's phrasing to determine mode. Default is merge.

Step 3: Build Internal Maps (graph.json only — skip for OKF bundles)

Before writing anything, build two maps from the links array:

Adjacency map — for each node id, collect all neighbour ids (edges in either direction):

adjacency["concepts/transformers"] = ["entities/vaswani", "concepts/lstm", ...]

Typed edge map — for each node id, collect outgoing typed edges only (typed: true):

typed_edges["concepts/transformers"] = [
  {target: "concepts/lstm", relation: "contradicts"},
  ...
]

Step 4-Graph: Reconstruct Pages from graph.json (graph.json source only)

Record counts: created = 0, skipped = 0, merged = 0.

For each node in nodes:

1. Compute page_path = $VAULT/<node.id>.md
2. Ensure the parent directory exists (e.g. $VAULT/concepts/)
3. Check if the file already exists:
   • merge mode (default) + exists → read existing file, apply merge logic (see below), increment merged
   • merge mode (default) + doesn't exist → proceed to create stub, increment created
   • skip mode + exists → increment skipped, continue to next node
   • skip mode + doesn't exist → proceed to create stub, increment created
   • overwrite mode + exists → proceed to write fresh stub (overwrite), increment merged
   • overwrite mode + doesn't exist → proceed to create stub, increment created

Page template (new or overwrite)

---
title: <node.label>
category: <node.category>
tags: <node.tags as YAML list>
sources:
  - "imported from <graph.json path>"
<if node.summary exists>
summary: "<node.summary>"
</if>
<if typed_edges[node.id] is non-empty>
relationships:
<for each {target, relation} in typed_edges[node.id]>
  - target: "[[<target>]]"
    type: <relation>
</for>
</if>
lifecycle: draft
lifecycle_changed: <today YYYY-MM-DD>
base_confidence: 0.5
tier: supporting
created: <ISO timestamp>
updated: <ISO timestamp>
---

# <node.label>

<node.summary paragraph if available, else omit>

## Related

<for each neighbour in adjacency[node.id], sorted alphabetically>
<if edge is typed>
- [[<neighbour>]] — <relation>
<else>
- [[<neighbour>]]
</if>
</for>

If adjacency[node.id] is empty, omit the ## Related section entirely.

Merge logic (merge mode, existing page)

1. Read the existing page's frontmatter.
2. Tags: union of existing tags and node.tags (deduplicated, keep existing order, append new ones).
3. Summary: if the existing page has no summary field and node.summary exists, add it.
4. Relationships: union of existing relationships: entries and typed_edges[node.id] — skip entries where the same (target, type) pair already exists.
5. Updated: set updated to the current ISO timestamp.
6. Body: scan for a ## Related section. If it exists, append any missing wikilinks from adjacency[node.id] that aren't already linked anywhere in the body. If no ## Related section exists, append one with the missing links.
7. Leave the rest of the body untouched.

Step 4-OKF: Reconstruct Pages from an OKF bundle (OKF source only)

Record counts: created = 0, skipped = 0, merged = 0, unparseable = 0.

Walk the bundle directory tree. For each .md file that is not a reserved file (index.md, log.md):

1. Parse the YAML frontmatter. If it has no frontmatter or no non-empty type, increment unparseable and skip the file.
2. Compute the concept id = the file's path relative to the bundle root, with .md stripped (e.g. concepts/transformers.md → concepts/transformers). The target page is $VAULT/<concept-id>.md.
3. Reverse-map frontmatter (the inverse of the canonical mapping table in wiki-export Step 3.5):
   • title ← title.
   • category ← the preserved category extension key if present; else lower-case the directory prefix of the concept id (concepts/… → concepts); else derive from type (Concept→concepts, Entity→entities, Skill→skills, Reference→references, Synthesis→synthesis, Project→projects, Journal→journal).
   • tags ← tags.
   • summary ← description.
   • updated ← timestamp (or now if absent).
   • created ← the preserved created extension key if present, else now.
   • sources ← the preserved sources extension key if present; else ["imported from OKF bundle <bundle path>"]. If a resource URL is present and not already in sources, add it.
   • Carry through any other preserved extension keys verbatim (relationships, lifecycle, tier, base_confidence, …). These make the round-trip lossless.
4. Reverse-transform body links — markdown links that point at .md paths become wikilinks (this restores both real cross-links and forward-references the exporter preserved per wiki-export Step 3.5):
   • [text](../concepts/transformers.md) or [text](/concepts/transformers.md) → resolve the path (relative to this file's dir, or bundle-root for /-absolute) to a concept id → [[concepts/transformers]], or [[concepts/transformers|text]] when text differs from the target's title. The target's title comes from the bundle page when it exists; otherwise compare against the last path segment.
   • Treat the markdown target as a file path first: normalize the .md path relative to the current file, then strip the trailing .md from the resolved file path to recover the page id. Do not try to infer the id from directory traversal segments before resolving the full file path. This preserves round-trips for folder-note layouts like projects/social-twitter.md plus projects/social-twitter/..., where ../../social-twitter.md must restore to projects/social-twitter.
   • This applies even when the target page is not in the bundle — a path-form link to a not-yet-written page round-trips back to a dangling [[wikilink]] (Obsidian supports these; OKF §5.3 expects them). Do not leave it as a markdown link.
   • When OBSIDIAN_LINK_FORMAT=markdown is set in config, keep markdown links (just rewrite the path to be vault-relative); do not convert to wikilinks.
   • Leave external http(s):// links and # Citations sections untouched.
5. Write the page using the conflict mode from Step 2:
   • merge + exists → reverse-map frontmatter and merge it into the existing page (union tags; fill summary/sources only if missing; union relationships; refresh updated). For the body, OKF carries a real body: replace the existing body with the bundle body only if the existing page is a stub (body is just a heading + ## Related); otherwise keep the existing body and append any bundle # Citations / new ## sections not already present. Increment merged.
   • merge + doesn't exist → write the full page (frontmatter + full bundle body). Increment created.
   • skip + exists → increment skipped, continue.
   • skip + doesn't exist → write the full page. Increment created.
   • overwrite + exists → write the full page, replacing the existing one. Increment merged (label as Replaced in the summary).
   • overwrite + doesn't exist → write the full page. Increment created.
6. Ensure the parent directory ($VAULT/concepts/, etc.) exists before writing.

Unlike the graph.json path, do not generate a ## Related stub section — the bundle body already contains the real cross-links.

Step 5: Update Vault Metadata

.manifest.json

Add a new entry keyed by the canonical path of the graph.json file:

"<absolute path to source>": {
  "ingested_at": "<ISO timestamp>",
  "source_type": "wiki-export",
  "pages_created": ["list/of/created/pages.md"],
  "pages_updated": ["list/of/merged/pages.md"]
}

Set source_type to "wiki-export" for a graph.json import or "okf-bundle" for an OKF bundle import. Key the entry by the absolute path of the source (the graph.json file or the bundle directory).

Also increment:

• stats.total_sources_ingested by 1
• stats.total_pages by the count of pages actually created (not skipped/merged)

If .manifest.json doesn't exist, create it with the standard structure:

{
  "stats": {
    "total_sources_ingested": 1,
    "total_pages": <created count>
  },
  "<graph.json path>": { ... }
}

index.md

For each created or merged page:

• Add or update the entry under its category section using the format: - [[<id>]] — <summary or title> ( #tag1 #tag2) (Note: space before ( — description ( #tag) not description(#tag))

Keep categories sorted alphabetically. Create the category section if it doesn't exist.

log.md

Append one line:

- [<ISO timestamp>] IMPORT source="<graph.json path>" pages_created=<N> pages_skipped=<K> pages_merged=<M>

hot.md

Rewrite the Recent Activity section to include this import as the latest entry:

- [<timestamp>] IMPORT from <graph.json path> — created X, merged Z pages

Update the updated: frontmatter timestamp. Leave other hot.md sections (Active Threads, Key Takeaways) intact unless they reference pages that were just created — in which case add brief mentions.

Step 6: Print Summary

Wiki import complete → $OBSIDIAN_VAULT_PATH
  Source:  <source path>  (<graph.json | OKF bundle>)
           <graph: exported at <graph.exported_at>, N nodes, M links | okf: N pages, okf_version <ver>>
  Created: <X> pages
  Merged:  <Z> pages  (existing pages updated)
  Skipped: <Y> pages  (only when --skip mode was used)

Only show the Skipped line if skip mode was explicitly requested. If overwrite mode was used, label merged pages as Replaced instead. For an OKF import, also report Unparseable: <U> files (no frontmatter/type, skipped) when U > 0.

Notes

• Stub vs full pages: A graph.json import produces stubs — structure and wikilinks but no body, a starting point for future ingestion. An OKF bundle import produces full pages with real bodies — it is the lossless, content-bearing path and the right choice for vault-to-vault transfer.
• Re-running is safe: The default merge mode is idempotent — re-running on an unchanged export will update timestamps but won't destroy content. Use overwrite only when you want to fully reset pages to stubs.
• Directory creation: Always create missing category directories before writing pages.
• Broken wikilinks: Since pages are being created together from the same export, most links will resolve. Any node referenced in links but absent from nodes (broken in the original export) will still appear as a wikilink — it just won't have a corresponding page file, which is valid.
• Filtered exports: If the source graph.json was produced with visibility filtering (noted in graph.metadata), imported pages will only reflect the filtered set. Note this in the summary if graph.graph contains a filtered key.

Wiki Rebuild — Archive, Rebuild, Restore

You are performing a destructive operation on the wiki. Always archive first, always confirm with the user before proceeding.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and optional QMD settings such as QMD_WIKI_COLLECTION
2. Read .manifest.json to understand current state
3. Confirm the user's intent. This skill supports three modes:
   • Archive only — snapshot current wiki, no rebuild
   • Archive + Rebuild — snapshot, then reprocess all sources from scratch
   • Restore — bring back a previous archive

The Archive System

Archives live at $OBSIDIAN_VAULT_PATH/_archives/. Each archive is a timestamped directory containing a full copy of the wiki state at that point.

$OBSIDIAN_VAULT_PATH/
├── _archives/
│   ├── 2026-04-01T10-30-00Z/
│   │   ├── archive-meta.json
│   │   ├── concepts/
│   │   ├── entities/
│   │   ├── skills/
│   │   ├── references/
│   │   ├── synthesis/
│   │   ├── journal/
│   │   ├── projects/
│   │   ├── index.md
│   │   ├── log.md
│   │   └── .manifest.json
│   └── 2026-03-15T08-00-00Z/
│       └── ...
├── concepts/          ← live wiki
├── entities/
└── ...

archive-meta.json

{
  "archived_at": "2026-04-06T10:30:00Z",
  "reason": "rebuild",
  "total_pages": 87,
  "total_sources": 42,
  "total_projects": 6,
  "vault_path": "/Users/name/Knowledge",
  "manifest_snapshot": ".manifest.json"
}

Mode 1: Archive Only

When the user wants to snapshot the current state without rebuilding.

Steps:

1. Create archive directory: _archives/YYYY-MM-DDTHH-MM-SSZ/
2. Copy all category directories, index.md, log.md, .manifest.json, and projects/ into the archive
3. Write archive-meta.json with reason "snapshot"
4. Append to log.md:

   - [TIMESTAMP] ARCHIVE reason="snapshot" pages=87 destination="_archives/2026-04-06T10-30-00Z"
   

5. Optionally refresh QMD if log.md is indexed and QMD_WIKI_COLLECTION is configured (see "QMD Refresh After Live Wiki Changes").
6. Report: "Archived 87 pages. Current wiki is untouched."

Mode 2: Archive + Rebuild

When the user wants to start fresh. This is the full sequence:

Step 1: Archive current state

Same as Mode 1 above, but with reason "rebuild".

Step 2: Clear live wiki

Remove all content from the category directories (concepts/, entities/, skills/, etc.) and the projects/ directory. Keep:

• _archives/ (obviously)
• .obsidian/ (Obsidian config)
• .env (if present in vault)

Reset index.md to the empty template. Reset log.md with just the rebuild entry. Delete .manifest.json (it'll be recreated during ingest).

Step 3: Rebuild

Tell the user the vault is cleared and ready for a full re-ingest. They can now run:

1. wiki-status — to see all sources as "new"
2. claude-history-ingest — to reprocess Claude history
3. codex-history-ingest — to reprocess Codex session history
4. wiki-ingest — to reprocess documents and any other raw data

Each of these will rebuild the manifest as they go.

Important: Don't run the ingest yourself automatically. The user should choose what to re-ingest and in what order. Some sources may no longer be relevant.

Step 4: Log the rebuild

Append to log.md:

- [TIMESTAMP] REBUILD archived_to="_archives/2026-04-06T10-30-00Z" previous_pages=87

Refresh QMD after clearing and logging the live wiki (see "QMD Refresh After Live Wiki Changes"), then report that the vault is ready for selected re-ingest skills.

Mode 3: Restore from Archive

When the user wants to go back to a previous state.

Step 1: List available archives

Read _archives/ directory. For each archive, read archive-meta.json and present:

## Available Archives

| Date | Reason | Pages | Sources |
|---|---|---|---|
| 2026-04-06 10:30 | rebuild | 87 | 42 |
| 2026-03-15 08:00 | snapshot | 65 | 31 |

Step 2: Confirm which archive to restore

Ask the user which archive they want. Warn them that restoring will overwrite the current live wiki.

Step 3: Archive current state first

Before restoring, archive the current state (reason: "pre-restore") so nothing is lost.

Step 4: Restore

1. Clear the live wiki (same as Mode 2, Step 2)
2. Copy all content from the chosen archive back into the live wiki directories
3. Restore index.md, log.md, and .manifest.json from the archive
4. Append to log.md:

   - [TIMESTAMP] RESTORE from="_archives/2026-03-15T08-00-00Z" pages_restored=65
   

Step 5: Report

Refresh QMD after restore (see "QMD Refresh After Live Wiki Changes"), then tell the user what was restored and suggest running wiki-lint to check for any issues with the restored state.

QMD Refresh After Live Wiki Changes

QMD is a search index, not the source of truth. If QMD refresh fails, do not roll back archive, rebuild, or restore work; report the failure and leave the markdown vault intact.

GUARD: If $QMD_WIKI_COLLECTION is empty or unset, skip this step.

When to run:

This refresh currently requires the local QMD CLI. Use $QMD_CLI if set; otherwise use qmd. If the CLI is unavailable, report QMD skipped: qmd CLI unavailable.

For CLI refresh:

${QMD_CLI:-qmd} update

If the output says new hashes need vectors, or if restore replaced live pages and embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the wiki collection reflects the operation:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

For restore, also verify one restored page if the archive has a known page path:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<restored-page>.md" -l 5

Record QMD refresh in the final report as one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: archive-only live content unchanged
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Safety Rules

1. Always archive before destructive operations. No exceptions.
2. Always confirm with the user before clearing the live wiki.
3. Never delete archives unless the user explicitly asks. Archives are cheap insurance.
4. The .obsidian/ directory is sacred. Never touch it during archive/rebuild/restore — it contains the user's Obsidian settings, plugins, and themes.
5. If something goes wrong mid-rebuild, the archive is there. Tell the user they can restore.

Wiki Research — Autonomous Multi-Round Research

You are running an autonomous research loop on a topic, synthesizing what you find, and filing the results into the Obsidian wiki as permanent knowledge.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and OBSIDIAN_LINK_FORMAT (default: wikilink).
2. Read $OBSIDIAN_VAULT_PATH/index.md to understand what's already in the wiki — don't re-research things the wiki covers well
3. Read $OBSIDIAN_VAULT_PATH/hot.md if it exists — it surfaces recent context
4. Check $OBSIDIAN_VAULT_PATH/references/research-config.md if it exists — it may define source preferences, domains to skip, or confidence rules for this vault

When writing internal links in generated pages, apply the link format from llm-wiki/SKILL.md (Link Format section) using the OBSIDIAN_LINK_FORMAT value.

Confirm the research topic with the user if it's ambiguous. Then proceed.

Research Configuration (optional)

If references/research-config.md exists in the vault, read it and apply any rules it defines:

• Source preferences (e.g., prefer academic sources, avoid certain domains)
• Domains to skip
• Confidence scoring adjustments
• Topic-specific constraints

If the file doesn't exist, proceed with defaults.

Round 1 — Broad Survey

Goal: Get a wide map of the topic.

1. Decompose the topic into 3-5 distinct angles (e.g., for "vector databases": what they are, when to use them, leading implementations, trade-offs, production gotchas)
2. For each angle, run 2-3 WebSearch queries using varied phrasing
3. For the top 2-3 results per angle, use WebFetch (or defuddle <url> if available — cleaner extraction) to get content
4. From each fetched page, extract:
   • Key claims — what the source explicitly states
   • Concepts — ideas, terms, frameworks introduced
   • Entities — tools, people, organizations mentioned
   • Contradictions — places where sources disagree with each other

Track what's covered and what's missing as you go.

Round 2 — Gap Fill

Goal: Close the holes left by Round 1.

Review what Round 1 produced:

• What questions did sources raise but not answer?
• Where do sources contradict each other?
• Which angles got thin coverage?

Run up to 5 targeted searches specifically addressing these gaps. Prefer primary sources, official documentation, and authoritative analyses over link aggregators.

Add findings to your working set. Update the contradiction list.

Round 3 — Synthesis Check

Goal: Resolve contradictions; confirm depth is sufficient.

If major contradictions remain unresolved:

• Run one final targeted pass (2-3 searches) to find authoritative resolution
• If resolution is impossible, flag the contradiction explicitly in the synthesis page

If contradictions are minor or the topic feels well-covered after Round 2, skip additional searching and proceed to filing.

Halt condition: Stop when depth is achieved or 3 rounds are complete — do not loop indefinitely.

Filing — Write Wiki Pages

Organize all findings into wiki pages across four output areas:

1. sources/ — One page per major reference

For each significant source (typically 4-8 pages total):

---
title: >-
  <Source title>
category: references
tags: [<2-4 domain tags>]
sources:
  - "<URL>"
source_url: "<URL>"
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
summary: >-
  <1-2 sentences describing what this source covers, ≤200 chars>
provenance:
  extracted: 0.X
  inferred: 0.X
  ambiguous: 0.X
base_confidence: <0.17 + 0.5 × classify(url) for a single source>
lifecycle: draft
lifecycle_changed: <ISO date today>
---

Body: title, URL, what it covers, key claims (with provenance markers), limitations.

2. concepts/ — One page per substantive concept

For each significant concept surfaced across sources:

Standard concept frontmatter + body. Link concepts to each other and to source pages.

3. entities/ — Tools, organizations, people

For each significant entity encountered (tools, libraries, companies, key authors):

Standard entity frontmatter. Link back to concepts that use the entity and sources where it appears.

4. synthesis/Research: [Topic].md — Master synthesis

The primary output: a structured synthesis of everything found.

---
title: >-
  Research: <Topic>
category: synthesis
tags: [<3-5 domain tags>, research]
sources: [<list of source URLs or page paths>]
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
summary: >-
  Synthesis of <N>-round research on <topic>. Covers <core findings in ≤200 chars>.
provenance:
  extracted: 0.X
  inferred: 0.X
  ambiguous: 0.X
base_confidence: <min(N_unique_sources/3,1.0)×0.5 + avg_source_quality×0.5>
lifecycle: draft
lifecycle_changed: <ISO date today>
---

# Research: <Topic>

## Overview
<2-4 sentence executive summary of what the research found>

## Key Findings
<Bulleted list of the most important claims, each with a [[source page]] citation>

## Core Concepts
<Links to concept pages created, with one-line descriptions>

## Entities & Tools
<Links to entity pages, with one-line descriptions>

## Contradictions & Open Questions
<Where sources disagree or where the research hit limits>

## Sources Consulted
<Linked list of all source pages>

Cross-linking

After filing all pages:

• Every concept page should link to at least 2 source pages
• Every source page should link to the concept pages it informed
• The synthesis page should link to all concept, entity, and source pages produced

Check index.md for existing pages on the same topics — merge into existing pages rather than creating duplicates.

Update Tracking Files

.manifest.json — Add a research entry:

{
  "type": "research",
  "topic": "<topic>",
  "researched_at": "TIMESTAMP",
  "rounds_completed": 3,
  "sources_fetched": N,
  "pages_created": ["..."],
  "pages_updated": ["..."]
}

index.md — Add all new pages under their respective sections.

log.md — Append:

- [TIMESTAMP] WIKI_RESEARCH topic="<topic>" rounds=N sources_fetched=N pages_created=M

hot.md — Update Recent Activity with the research topic and core finding. Update Active Threads if this is ongoing. Update updated timestamp.

Quality Checklist

• 3 rounds completed (or halted at sufficient depth)
• Synthesis page exists at synthesis/Research: [Topic].md
• Source pages written for major references
• Concept and entity pages written for significant items
• Contradictions flagged in synthesis page
• All pages cross-linked
• index.md, log.md, hot.md, .manifest.json updated

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

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:

1. Where should the vault live? → OBSIDIAN_VAULT_PATH

   • Default: ~/Documents/obsidian-wiki-vault
   • Must be an absolute path (after expansion)

2. Where are your source documents? → OBSIDIAN_SOURCES_DIR

   • Can be multiple paths, comma-separated
   • Default: ~/Documents

3. Want to import Claude history? → CLAUDE_HISTORY_PATH

   • Default: auto-discovers from ~/.claude
   • Set explicitly if Claude data is elsewhere

4. 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).

5. 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

6. 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):

1. Dataview — Query page metadata, create dynamic tables. Essential for a wiki.
2. Graph Analysis — Enhanced graph view for exploring connections.
3. Templater — If they want to create pages manually using templates.
4. 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:

1. Open the vault in Obsidian (File → Open Vault → select the directory)
2. Run wiki-status to see what's available to ingest
3. Run wiki-ingest to add their first sources
4. Run claude-history-ingest to mine their Claude conversations
5. Run codex-history-ingest to mine their Codex sessions (if they use Codex)
6. 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:

1. 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.

2. 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.

3. 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.

Wiki Stage Commit — Staged Write Promotion

You are reviewing LLM-written pages that are waiting in _staging/ for human approval before they land in the live wiki. This skill is only useful when WIKI_STAGED_WRITES=true in the vault config.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md. This gives OBSIDIAN_VAULT_PATH and WIKI_STAGED_WRITES.
2. If WIKI_STAGED_WRITES is not set or is false, tell the user: "Staged writes mode is not enabled. Set WIKI_STAGED_WRITES=true in your .env to use this feature." Then stop.
3. Read the _staging/ directory inventory.

Invocation Forms

/wiki-stage-commit               # interactive review: show each file and ask accept/reject
/wiki-stage-commit --all         # accept all staged files without per-file review
/wiki-stage-commit --reject-all  # reject all staged files (move to _raw/ for manual editing)
/wiki-stage-commit --list        # list staged files with summary, no changes

Step 1: Inventory Staged Files

Glob $OBSIDIAN_VAULT_PATH/_staging/**/*.md — these are the pending pages.

Also glob $OBSIDIAN_VAULT_PATH/_staging/**/*.patch.md — these are pending updates to existing pages (diff-style files showing proposed additions and deletions).

Report the inventory:

Staged files: 4 new pages, 2 updates

New pages:
  _staging/concepts/attention-mechanism.md        (ingested 2 days ago)
  _staging/entities/andrej-karpathy.md            (ingested 2 days ago)
  _staging/skills/fine-tuning-llms.md             (ingested yesterday)
  _staging/references/attention-is-all-you-need.md (ingested 3 hours ago)

Updates (patch files):
  _staging/concepts/transformer-architecture.patch.md  (target: concepts/transformer-architecture.md)
  _staging/skills/prompt-engineering.patch.md          (target: skills/prompt-engineering.md)

If _staging/ is empty, report: "Nothing staged. All writes have been committed or no staged writes have been produced yet."

Step 2: Per-File Review (interactive mode)

For each staged file (new pages first, then updates):

For new pages:

Display a summary:

--- New page: concepts/attention-mechanism.md ---
Title:    Attention Mechanism
Tags:     #ml #architecture
Summary:  Core building block of transformers — computes weighted sum of values based on query-key similarity.
Tier:     supporting
Confidence: 0.72
Sources:  papers/attention.pdf

[Preview first 20 lines of body]
...

Accept [a], Reject [r], Skip [s], Preview full [p]?

For patch files:

Display a structured diff:

--- Update: concepts/transformer-architecture.md ---
Source: _staging/concepts/transformer-architecture.patch.md

Proposed additions (+):
+ Transformers outperform RNNs on tasks requiring long-range dependencies. ^[inferred]
+ New source: papers/survey-2026.pdf

Proposed deletions (-):
- The attention mechanism was first described in [Bahdanau 2015].  (to be replaced by updated claim)

⚠️  Conflict check: target page was modified 3 days after staging. Review carefully.

Accept [a], Reject [r], Skip [s], Preview full diff [p]?

If --all flag is set, skip prompting and accept every file. If --reject-all flag is set, skip prompting and reject every file. If --list flag is set, stop after printing the inventory (Step 1).

Step 3: Apply Decisions

Accepting a new page

1. Move _staging/<category>/page.md → <category>/page.md (the final location)
2. Update index.md with the new page entry
3. Remove the staged file

Accepting a patch/update

1. Read the current page at the target path
2. Apply the proposed additions and deletions (merge, don't just overwrite)
3. Update the updated frontmatter timestamp
4. Update index.md if the summary changed
5. Remove the staged patch file

Rejecting a file

Move it to $OBSIDIAN_VAULT_PATH/_raw/ for manual editing:

• _staging/concepts/page.md → _raw/rejected-concepts-page.md
• _staging/concepts/page.patch.md → _raw/rejected-patch-concepts-page.md
• Prefix with rejected- so the user can identify it

Conflict detection on patch accept

Before applying a patch, check whether the target page's updated frontmatter is newer than the patch file's own updated field:

• If the target was modified AFTER the patch was staged, warn: ⚠️ Conflict: target was updated since this patch was staged. Applying may lose recent changes.
• Give the user a chance to abort: Apply anyway [y], Skip [s], Reject [r]?

Step 4: Update Tracking Files

After processing all staged files:

1. hot.md — update the Recent Activity section: "Committed N staged pages; rejected M."
2. log.md — append:

   - [TIMESTAMP] STAGE_COMMIT accepted=N rejected=M skipped=K
   

Step 5: Report

Stage commit complete.

✅  Accepted (N):
  concepts/attention-mechanism.md     → now live
  entities/andrej-karpathy.md         → now live
  concepts/transformer-architecture.md → updated (patch applied)

❌  Rejected (M):
  skills/fine-tuning-llms.md          → moved to _raw/rejected-skills-fine-tuning-llms.md

⏭️  Skipped (K):
  references/attention-is-all-you-need.md → still in _staging/

Staging queue: K files remaining

Notes

• Staged files use the same page template as live pages — they are ready to land, just awaiting approval
• Patch files use a human-readable diff format: lines starting with + are additions, lines starting with - are deletions
• index.md and log.md are always updated immediately on ingest (they are low-risk tracking files) — only category pages go through staging
• The _staging/ directory is not tracked by Obsidian's graph view — pages only appear in the wiki after promotion

Wiki Switch — Manage Multiple Vault Profiles

Each vault is a complete config file at ~/.obsidian-wiki/config.<name>. The active vault is whichever file ~/.obsidian-wiki/config symlinks to. Switching vaults means re-pointing that symlink.

Switch vs. inline targeting. /wiki-switch <name> changes your persistent default (re-points the symlink, affecting all future requests). To touch a different vault for just one request without changing your default, use the inline @name override in any request (e.g. @work save this, wiki-query @personal about X). The @name override is handled by the Config Resolution Protocol in llm-wiki/SKILL.md, not by this skill — it resolves ~/.obsidian-wiki/config.<name> for that one invocation and never re-points the symlink.

Dispatch

Parse the invocation and route to the right section:

Switch (default action)

Activate a named vault profile.

1. Verify ~/.obsidian-wiki/config.<name> exists. If not, tell the user the vault doesn't exist and list what's available (run List).
2. Run:

   ln -sf ~/.obsidian-wiki/config.<name> ~/.obsidian-wiki/config
   

3. Read OBSIDIAN_VAULT_PATH from the newly active config.
4. Confirm to the user:

   Switched to vault: <name>
   Vault path: <value of OBSIDIAN_VAULT_PATH from the config>
   

List

Show all registered vault profiles and which is active.

1. Find all files matching ~/.obsidian-wiki/config.* (exclude config itself — that's the symlink).
2. Resolve the current symlink target: readlink ~/.obsidian-wiki/config
3. For each config file, read the first non-empty comment line (lines starting with #) as a human description of the vault. Fall back to the file's suffix as the label if no comment exists.
4. Display:

   Vaults:
     personal   My personal research wiki    ← active
     work       Work projects wiki
   

   Mark the active one with ← active. If the symlink is broken or config doesn't exist, show (none active).

Show

Print the full config for a vault.

• If a name is given, read ~/.obsidian-wiki/config.<name>.
• If no name given, read ~/.obsidian-wiki/config (the active vault).
• If the file doesn't exist, tell the user and list what's available.
• Print the file contents verbatim (redact any lines containing API_KEY or SECRET — show *** instead of the value).

New

Scaffold a new vault config from the current active config as a template.

1. Check ~/.obsidian-wiki/config.<name> doesn't already exist. Abort if it does.
2. Copy the active config:

   cp ~/.obsidian-wiki/config ~/.obsidian-wiki/config.<name>
   

3. Read the copied config. Config files use # --- Section name --- comment headers to group fields into sections (e.g., # --- Vault-specific ---, # --- Vault-independent ---, # --- Secrets ---). Use these sections to determine what to ask about:
   • Fields in sections labeled "vault-specific", "paths", or similar → ask the user for new values
   • Fields in sections labeled "vault-independent", "global", "shared" → keep as-is (copy over unchanged)
   • Fields in sections labeled "secrets" → ask if the new vault uses the same credentials or different ones
   • If there are no section headers, present all fields and let the user decide which to change
4. Ask the user for updated values for the vault-specific fields. Use the current values as visible defaults — the user only needs to supply what differs.
5. Write the updated values into ~/.obsidian-wiki/config.<name>.
6. Update the top comment line to describe the new vault (e.g., # Obsidian Wiki — <name> vault).
7. Confirm:

   Created: ~/.obsidian-wiki/config.<name>
   Run `/wiki-switch <name>` to activate it, then run `wiki-setup` to initialise the new vault.
   

   Do not switch automatically — let the user decide when to activate.

Wiki Synthesize — First-Class Synthesis Discovery

You are scanning the wiki for concepts that co-occur across many pages but have no dedicated synthesis page connecting them. Your job is to surface these gaps and fill the most valuable ones with cross-cutting synthesis pages.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and OBSIDIAN_LINK_FORMAT (default: wikilink).
2. Read index.md to get the full page inventory.
3. Read hot.md if it exists — it surfaces recent activity and active threads that may already point to synthesis opportunities.
4. Read _meta/taxonomy.md to understand the tag vocabulary.

When writing internal links in synthesis pages, apply the link format from llm-wiki/SKILL.md (Link Format section) using the OBSIDIAN_LINK_FORMAT value.

Step 1: Build the Co-occurrence Map

Scan every non-special page in the vault (skip index.md, log.md, hot.md, _insights.md, _meta/*, _archives/*, _raw/*).

For each page, collect:

• All [[wikilinks]] it contains (outgoing links)
• Its tags frontmatter
• Its category frontmatter

Build a co-occurrence matrix: for every pair of concept/entity pages (A, B), count how many other pages link to both A and B. This is their co-occurrence score.

You don't need to be exhaustive — aim for the top 20-30 pairs by co-occurrence score. Use Grep to find backlinks efficiently:

grep -rl "\[\[ConceptA\]\]" "$OBSIDIAN_VAULT_PATH" --include="*.md"

Run this for your top candidate concepts and intersect the result sets.

Step 2: Filter Out Already-Synthesized Pairs

Check the synthesis/ directory for existing pages. For each existing synthesis page:

• Read its sources frontmatter or its body for [[wikilinks]]
• Mark those concept pairs as already covered

Remove covered pairs from your candidate list.

Step 3: Score and Rank Candidates

For each remaining candidate pair (or cluster of 3+), assign a synthesis value score:

Pick the top 5 candidates. If the user asked for a specific topic ("synthesize everything about observability"), filter candidates to that domain first.

Step 4: Draft Synthesis Pages

For each top candidate, create a page in synthesis/ using this template:

---
title: <Concept A> × <Concept B>
category: synthesis
tags: [<shared tags>, <domain tags>]
sources: [<all pages that link to both>]
created: TIMESTAMP
updated: TIMESTAMP
summary: "Cross-cutting synthesis of how <A> and <B> interact, with implications for <domain>."
provenance:
  extracted: 0.2
  inferred: 0.7
  ambiguous: 0.1
base_confidence: <min(base_confidence of all input pages)>
lifecycle: draft
lifecycle_changed: TIMESTAMP_DATE
---

# <Concept A> × <Concept B>

## The Connection

*What makes these two concepts worth synthesizing together — the non-obvious relationship that pages about each individually don't capture.*

## Where They Co-occur

*The pages and contexts where both appear. What situations bring them together.*

## Cross-cutting Insight

*The conclusion that only becomes visible when you look at both together. This is the point of the page — the thing you couldn't see from either concept page alone.*

## Tensions and Trade-offs

*Where the two concepts pull in opposite directions. Unresolved contradictions. Cases where applying one undermines the other.*

## Strongest Objection

*The best skeptical reading of THIS page's cross-cutting insight — the case a sharp critic would make that the connection is spurious, overstated, or an artifact of how the sources were written. Follow it with a testable search query (e.g. `> test: does X actually hold when Y is controlled for?`), never an invented citation. A synthesis that can't name its own strongest objection hasn't earned its conclusion.*

## Open Questions

*What this synthesis surfaces that the wiki doesn't yet have an answer for. Good candidates for future research.*

## Related

- [[<Concept A>]]
- [[<Concept B>]]
- [[<other related pages>]]

Synthesis pages are mostly ^[inferred]. You are drawing connections across sources — that's synthesis by definition. Apply ^[inferred] to cross-cutting conclusions and ^[ambiguous] where sources disagree.

The title format is A × B — this signals to readers that it's a synthesis page, not a page about either concept alone.

Step 5: Back-link from Source Pages

For each synthesis page you created, add a link to it from the two (or more) concept pages it synthesizes. In the concept page, add to its ## Related section:

- [[Concept A × Concept B]] — synthesis

If the concept page has no ## Related section, add one at the bottom.

Step 6: Report Synthesis Opportunities Not Taken

After creating pages for the top 5, list the next 10 candidates in your output — pairs that scored well but you didn't write pages for. This gives the user visibility into what the wiki thinks is worth exploring without forcing every synthesis in one run.

Format:

Skipped (consider next time):
- [[Caching]] × [[Consistency]] — co-occurs in 4 pages, cross-domain
- [[Testing]] × [[Observability]] — co-occurs in 3 pages, shares tags
...

Step 7: Update Special Files

index.md — Add entries for all new synthesis pages.

log.md — Append:

- [TIMESTAMP] WIKI_SYNTHESIZE pages_scanned=N synthesis_created=M candidates_skipped=K

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with what was synthesized — e.g. "Synthesized 5 cross-cutting pages: Caching × Consistency, Testing × Observability, …". Update Active Threads with any open questions the synthesis surfaced. Update updated timestamp.

Quality Checklist

• Every synthesis page has a summary: field (≤200 chars)
• Every synthesis page links back to its source concepts
• Source concept pages link forward to the synthesis page
• No synthesis page just restates what's already on the source pages — it must add a cross-cutting insight
• Every synthesis page names its Strongest Objection with a testable search query (not an invented source)
• index.md and log.md updated
• hot.md updated

Tips

• A synthesis page that only summarizes its sources is useless. The value is the connection — the thing neither source page says explicitly.
• Don't synthesize for synthesis's sake. If two concepts just happen to appear together a lot without a real conceptual link, skip them.
• Three-way syntheses are powerful but rare. Only create them when three concepts form a genuine triangle of mutual influence — not just because all three appear in the same project page.
• Check _insights.md first. The wiki-status skill may have already flagged synthesis candidates there — start with those before running the co-occurrence scan from scratch.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Wiki Update — Sync Any Project to Your Wiki

You are distilling knowledge from the current project into the user's Obsidian wiki. This skill works from any project directory, not just the obsidian-wiki repo.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH, OBSIDIAN_WIKI_REPO, OBSIDIAN_LINK_FORMAT (wikilink default or markdown), and optional QMD settings such as QMD_WIKI_COLLECTION. Works from any project directory.
2. Read $OBSIDIAN_VAULT_PATH/.manifest.json to check if this project has been synced before.
3. Read $OBSIDIAN_VAULT_PATH/index.md to know what the wiki already contains.

When writing internal links in Steps 4–5, apply the link format from llm-wiki/SKILL.md (Link Format section) using the OBSIDIAN_LINK_FORMAT value.

Step 1: Understand the Project

Figure out what this project is by scanning the current working directory:

• README.md, docs/, any markdown files
• Source structure (frameworks, languages, key abstractions)
• package.json, pyproject.toml, go.mod, Cargo.toml or whatever defines the project
• Git log (focus on commit messages that signal decisions, not "fix typo" stuff)
• Claude memory files if they exist (.claude/ in the project)

Derive a clean project name from the directory name.

Step 2: Compute the Delta

Check .manifest.json for this project:

• First time? Full scan. Everything is new.
• Synced before? Look at last_commit_synced. Before computing the delta, verify the stored SHA is still reachable:

  git merge-base --is-ancestor <last_commit_synced> HEAD
  

  • Exit 0 (ancestor): Safe. Run git log <last_commit_synced>..HEAD --oneline to see what changed.
  • Exit 1 (not an ancestor — rebase or force-push occurred): The stored SHA is no longer in this branch's history. Warn the user: "Stored commit <sha> is no longer reachable — branch may have been rebased or force-pushed. Falling back to full scan." Then treat as first-time sync: re-scan everything and update last_commit_synced to the current HEAD SHA at the end of Step 6.

If nothing meaningful changed since last sync, tell the user and stop.

Step 3: Decide What to Distill

This is the core question from Karpathy's pattern: what would you want to know about this project if you came back in 3 months with zero context?

Worth distilling:

• Architecture decisions and why they were made
• Patterns discovered while building (things you'd Google again otherwise)
• What tools, services, APIs the project depends on and how they're wired together
• Key abstractions, how they connect, what the mental model is
• Trade-offs that were evaluated, what was picked and why
• Things learned while building that aren't obvious from reading the code

Not worth distilling:

• File listings, boilerplate, config that's obvious
• Individual bug fixes with no broader lesson
• Dependency versions, lock file contents
• Implementation details the code already says clearly
• Routine changes anyone could read from the diff

The heuristic: if reading the codebase answers the question, don't wiki it. If you'd have to re-derive the reasoning by reading git blame across 20 commits, wiki it.

Step 4: Distill into Wiki Pages

Project-specific knowledge

Goes under $VAULT/projects/<project-name>/:

projects/<project-name>/
├── <project-name>.md          ← project overview (named after the project, NOT _project.md)
├── concepts/                  ← project-specific ideas, architectures
├── skills/                    ← project-specific how-tos, patterns
└── references/                ← project-specific source summaries

The overview page (<project-name>.md) should have:

• What the project is (one paragraph)
• Key concepts and how they connect
• Links to project-specific and global wiki pages

Global knowledge

Things that aren't project-specific go in the global categories:

Page format

Every page needs YAML frontmatter:

---
title: >-
    Page Title
category: concepts
tags: [tag1, tag2]
sources: [projects/<project-name>]
summary: >-
    One or two sentences (≤200 chars) describing what this page covers.
provenance:
  extracted: 0.6
  inferred: 0.35
  ambiguous: 0.05
base_confidence: 0.59
lifecycle: draft
lifecycle_changed: TIMESTAMP_DATE
created: TIMESTAMP
updated: TIMESTAMP
---

Use folded scalar syntax (summary: >-) for title and summary to keep frontmatter parser-safe across punctuation (:, #, quotes) without escaping rules.
Keep the title and summary contents indented by two spaces under summary: >-.

# Page Title

- A fact the codebase or a doc actually states.
- A reason the design works this way. ^[inferred]

Use [[wikilinks]] to connect to other pages.

Write a summary: frontmatter field on every new/updated page (1–2 sentences, ≤200 chars), using >- folded style. For project sync, a good summary answers "what does this page tell me about the project I wouldn't guess from its title?" This field powers cheap retrieval by wiki-query.

Apply provenance markers per llm-wiki (Provenance Markers section). For project sync specifically:

• Extracted — anything visible in the code, config, or a doc/commit message: file structure, dependencies, function signatures, what a file does.
• Inferred — why a decision was made, design rationale, trade-offs, "the team chose X because Y" — unless a commit message, doc, or ADR states it explicitly.
• Ambiguous — when the code and docs disagree, or when there's clearly an in-progress migration with two patterns living side by side.

Compute the rough fractions and write the provenance: block on every new/updated page.

Updating vs creating

• If a page already exists in the vault, merge new information into it. Don't create duplicates.
• If you're adding to an existing page, update the updated timestamp and add the new source.
• Check index.md to see what's already there before creating anything new.

Step 5: Cross-link

After creating/updating pages:

• Add [[wikilinks]] from new pages to existing related pages
• Add [[wikilinks]] from existing pages back to the new ones where relevant
• Link the project overview to all project-specific pages and relevant global pages

Step 6: Update Tracking

Update .manifest.json

Add or update this project's entry:

{
  "projects": {
    "<project-name>": {
      "source_cwd": "/absolute/path/to/project",
      "last_synced": "TIMESTAMP",
      "last_commit_synced": "abc123f",
      "pages_in_vault": ["projects/<project-name>/<project-name>.md", "..."]
    }
  }
}

Update index.md

Add entries for any new pages created.

Update log.md

Append:

- [TIMESTAMP] WIKI_UPDATE project=<project-name> pages_updated=X pages_created=Y source_cwd=/path/to/project

Update hot.md

Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Rewrite Recent Activity with what was just synced — last 3 operations max. Update Active Threads if this project is an ongoing focus. Update Key Takeaways with the most important architectural insight or decision surfaced during this sync. Update updated timestamp.

Write conceptually: "Synced obsidian-wiki — added wiki-capture and wiki-research skills, core new capabilities are autonomous web research and conversation capture."

Step 7: Refresh QMD Wiki Index (optional — requires QMD_WIKI_COLLECTION)

GUARD: If $QMD_WIKI_COLLECTION is empty or unset, skip this step. The markdown vault is the source of truth; QMD is only a search index.

Run this step only after pages, .manifest.json, index.md, log.md, and hot.md have been written. If Step 2 found no meaningful changes and the sync stopped early, do not refresh QMD.

This refresh currently requires the local QMD CLI. Use $QMD_CLI if set; otherwise use qmd. If the CLI is unavailable or returns an error, do not roll back the wiki update; report that the wiki was updated but QMD refresh was skipped or failed.

For CLI refresh:

${QMD_CLI:-qmd} update

If the output says new hashes need vectors, or if pages were created/updated and embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify at least one created or materially updated page is visible in the wiki collection:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/projects/<project-name>/<page>.md" -l 5

If the exact qmd:// path is uncertain, use:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION" | grep "<project-name>"

Record QMD refresh in the final report as one of:

• QMD refreshed: update + embed + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Tips

• Be aggressive about merging. If the project uses React Server Components, don't create a new page if concepts/react-server-components.md already exists. Update the existing one and add this project as a source.
• Consult the tag taxonomy. Read $VAULT/_meta/taxonomy.md if it exists, and use canonical tags.
• Don't copy code. Distill the knowledge, not the implementation. "This project uses a debounced search pattern with 300ms delay" is useful. Pasting the actual debounce function is not.
• Project overview is the anchor. The <project-name>.md file is what you'd read to get oriented. Make it good.

Claude History Ingest — Conversation Mining

You are extracting knowledge from the user's past Claude Code conversations and distilling it into the Obsidian wiki. Conversations are rich but messy — your job is to find the signal and compile it.

This skill can be invoked directly or via the wiki-history-ingest router (/wiki-history-ingest claude).

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and CLAUDE_HISTORY_PATH (defaults to ~/.claude)
2. Read .manifest.json at the vault root to check what's already been ingested
3. Read index.md at the vault root to know what the wiki already contains
4. Project Scoping — read WIKI_SKIP_PROJECTS from config (comma-separated substrings). Exclude any project directory whose name contains one of them from every step below (scan, delta, sampling, manifest writes). If the user names extra projects to skip this run, add them. Apply the exclusion once, uniformly — don't hand-write grep -v filters into individual commands, which drifts between the scan and manifest steps.

Ingest Modes

Append Mode (default)

Check .manifest.json for each source file (conversation JSONL, memory file). Only process:

• Files not in the manifest (new conversations, new memory files, new projects)
• Files whose modification time is newer than their ingested_at in the manifest

This is usually what you want — the user ran a few new sessions and wants to capture the delta.

Canonical paths when comparing. The manifest keys are absolute paths with ~ expanded (see llm-wiki/SKILL.md → .manifest.json). Before deciding a file is "new", expand its path the same way — otherwise a file already tracked as ~/.claude/... looks new when you scanned it as /Users/me/.claude/... (or vice-versa) and gets re-ingested. The scripts/manifest.py helper does this for you:

# New/modified sources, honoring WIKI_SKIP_PROJECTS + --skip, paths already canonical:
python3 "$OBSIDIAN_WIKI_REPO/scripts/manifest.py" delta "$OBSIDIAN_VAULT_PATH" \
  --scan "$CLAUDE_HISTORY_PATH/projects/*/memory/*.md"
# One-time repair if the manifest already mixes ~ and absolute keys:
python3 "$OBSIDIAN_WIKI_REPO/scripts/manifest.py" normalize "$OBSIDIAN_VAULT_PATH" --dry-run

The helper is optional — if it's unavailable, do the same expansion inline before every manifest lookup and write.

Pre-extraction (recommended — run before ingest)

Raw JSONL files are 80-90% noise: tool_use blocks, thinking blocks, progress events, and file-history-snapshot entries dominate by byte count. The scripts/extract-jsonl.py helper strips all of that and writes compact signal-only JSON to ~/.claude/extracted/, achieving 50–200× file-size reduction (e.g. 12 MB JSONL → 64 KB extracted). This lets the skill read 5–10× more conversations per run within the same token budget.

Run it as a pre-step before invoking this skill:

# First run — extract everything (skip excluded projects)
python3 "$OBSIDIAN_WIKI_REPO/scripts/extract-jsonl.py" --skip tsg,autom8

# Incremental — only sessions modified in the last day
python3 "$OBSIDIAN_WIKI_REPO/scripts/extract-jsonl.py" \
    --since "$(date -v-1d +%Y-%m-%d)" --skip tsg,autom8

Extracted files live at ~/.claude/extracted/<project-dir>/<session-id>.json and contain:

{
  "session_id": "uuid",
  "project": "-Users-name-myapp",
  "cwd": "/Users/name/myapp",
  "start_ts": "...",
  "end_ts": "...",
  "n_turns": 18,
  "n_user_words": 620,
  "turns": [
    {"role": "user",      "text": "..."},
    {"role": "assistant", "text": "..."}
  ]
}

When Step 3 reads conversations, always prefer the extracted file over the raw JSONL. (See Step 3.)

If extract-jsonl.py was not run first, fall back to raw JSONL — but note the coverage will be shallower because each raw file costs far more tokens to read.

Conversation Sampling Heuristic

A history path can hold hundreds of conversation JSONLs — do not try to read them all. Per project:

• If the project already has memory files (memory/*.md), ingest those first (they are pre-distilled signal), then also process conversations not yet in the manifest — new conversations should still be captured even for memory-rich projects.
• If the project has no memory files, read only the 3 most recent conversations (by mtime) to characterize it. Prefer pre-extracted files (see above) — they are cheap enough that you can read 5–10 in the same token budget as 1 raw JSONL.
• Always report what you sampled vs skipped (e.g. "agenttower: 7 memory files + 4 new conversations ingested, 14 unchanged conversations skipped"), so the coverage gap is visible rather than silent.

Full Mode

Process everything regardless of manifest. Use after a wiki-rebuild or if the user explicitly asks.

Claude Code Data Layout

Claude Code stores data in two locations. Scan both.

Source 1: ~/.claude/ (CLI sessions)

~/.claude/
├── projects/                          # Per-project directories
│   ├── -Users-name-project-a/         # Path-derived name (slashes → dashes)
│   │   ├── <session-uuid>.jsonl       # Conversation data (JSONL)
│   │   └── memory/                    # Structured memories
│   │       ├── MEMORY.md              # Memory index
│   │       ├── user_*.md              # User profile memories
│   │       ├── feedback_*.md          # Workflow feedback memories
│   │       └── project_*.md           # Project context memories
│   ├── -Users-name-project-b/
│   │   └── ...
├── sessions/                          # Session metadata (JSON)
│   └── <pid>.json                     # {pid, sessionId, cwd, startedAt, kind, entrypoint}
├── history.jsonl                      # Global session history
├── tasks/                             # Subagent task data
├── plans/                             # Saved plans
└── settings.json

Source 2: ~/Library/Application Support/Claude/local-agent-mode-sessions/ (Desktop app agent sessions)

Pre-check first. Many users are CLI-only and have no desktop sessions. Before walking the structure below, confirm it's non-empty:

DESKTOP_SESSIONS="$HOME/Library/Application Support/Claude/local-agent-mode-sessions"
[ -d "$DESKTOP_SESSIONS" ] && find "$DESKTOP_SESSIONS" -name "audit.jsonl" | head -1

If that prints nothing, skip this entire section (Source 2 + Step 3b) and don't narrate it.

The Claude desktop app stores local agent mode sessions here. The structure is deeply nested:

~/Library/Application Support/Claude/local-agent-mode-sessions/
└── <outer-uuid>/
    └── <inner-uuid>/
        ├── local_<session-uuid>.json          # Session metadata
        └── local_<session-uuid>/
            ├── audit.jsonl                    # Audit log — tool calls, file reads, commands run
            └── .claude/
                └── projects/
                    └── <path-encoded-name>/   # Same path-encoding as ~/.claude/projects/
                        └── <uuid>.jsonl       # Conversation transcript (same JSONL format as CLI)

How to find all local-agent-mode sessions:

# Find all session metadata files
find ~/Library/Application\ Support/Claude/local-agent-mode-sessions -name "local_*.json" -maxdepth 4

# Find all audit logs
find ~/Library/Application\ Support/Claude/local-agent-mode-sessions -name "audit.jsonl"

# Find all conversation transcripts
find ~/Library/Application\ Support/Claude/local-agent-mode-sessions -name "*.jsonl" -path "*/.claude/projects/*"

Session metadata (local_<uuid>.json) — JSON file with fields like sessionId, cwd, startedAt, model, title. Read this first to understand the session context before opening the transcript.

Audit log (audit.jsonl) — Each line is a JSON record of one agent action: tool calls (Read, Write, Bash, Edit), file accesses, shell commands executed, MCP calls. Useful for understanding what the agent actually did — often richer signal than the conversation text alone. Fields: type, toolName, input, output, timestamp, sessionId.

Conversation transcript (.claude/projects/.../<uuid>.jsonl) — Identical format to CLI conversation JSONL. Parse the same way as ~/.claude/projects/*/*.jsonl.

Key data sources ranked by value (both locations combined):

1. Memory files (~/.claude/projects/*/memory/*.md) — Pre-distilled, already wiki-friendly. Gold.
2. Conversation JSONL (both ~/.claude/projects/*/*.jsonl and desktop app transcripts) — Full conversation transcripts. Rich but noisy.
3. Audit logs (audit.jsonl in desktop sessions) — Tool-call level record of what was done. Useful for extracting concrete actions, file patterns, and command patterns even when the conversation is sparse.
4. Session metadata (sessions/*.json and local_*.json) — Tells you which project, when, and what CWD.

Step 1: Survey and Compute Delta

Scan both data locations and compare against .manifest.json:

# --- Source 1: CLI sessions (~/.claude) ---
# Find all projects
Glob: ~/.claude/projects/*/

# Find memory files (highest value)
Glob: ~/.claude/projects/*/memory/*.md

# Find conversation JSONL files
Glob: ~/.claude/projects/*/*.jsonl

# --- Source 2: Desktop app local-agent-mode sessions ---
DESKTOP_SESSIONS="$HOME/Library/Application Support/Claude/local-agent-mode-sessions"

# Session metadata
find "$DESKTOP_SESSIONS" -name "local_*.json" -maxdepth 4

# Audit logs
find "$DESKTOP_SESSIONS" -name "audit.jsonl"

# Conversation transcripts
find "$DESKTOP_SESSIONS" -name "*.jsonl" -path "*/.claude/projects/*"

Build a unified inventory and classify each file:

• New — not in manifest → needs ingesting
• Modified — in manifest but file is newer → needs re-ingesting
• Unchanged — in manifest and not modified → skip in append mode

Report to the user: "Found X CLI projects, Y desktop sessions. Memory files: A. Conversations: B. Audit logs: C. Delta: D new, E modified."

Step 2: Ingest Memory Files First

Memory files are already structured with YAML frontmatter:

---
name: memory-name
description: one-line description
type: user|feedback|project|reference
---

Memory content here.

For each memory file:

• Read it and parse the frontmatter
• user type → feeds into an entity page about the user, or concept pages about their domain
• feedback type → feeds into skills pages (workflow patterns, what works, what doesn't)
• project type → feeds into entity pages for the project
• reference type → feeds into reference pages pointing to external resources

The MEMORY.md index file in each project is a quick summary — read it first to decide which individual memory files are worth reading in full.

Step 3: Parse Conversation JSONL

Always check for a pre-extracted file first (see Pre-extraction section above). For each conversation ~/.claude/projects/<proj>/<uuid>.jsonl, look for its counterpart at ~/.claude/extracted/<proj>/<uuid>.json. If found, read that instead — it is already filtered to user + assistant text turns and costs 50–200× fewer tokens than the raw JSONL.

# Resolution order for each session:
1. ~/.claude/extracted/<project>/<session-id>.json   ← prefer (compact, signal-only)
2. ~/.claude/projects/<project>/<session-id>.jsonl   ← fallback (raw, noisy)

Reading a pre-extracted file: it already contains only the turns you need. Iterate turns[].{role, text} directly. The top-level fields (cwd, start_ts, n_user_words, etc.) give you project context without any further parsing.

Reading raw JSONL (fallback): Each line is a JSON object:

{
  "type": "user|assistant|progress|file-history-snapshot",
  "message": {
    "role": "user|assistant",
    "content": "text string"
  },
  "uuid": "...",
  "timestamp": "2026-03-15T10:30:00.000Z",
  "sessionId": "...",
  "cwd": "/path/to/project",
  "version": "2.1.59"
}

For assistant messages, content may be an array of content blocks:

{
  "content": [
    {"type": "thinking", "text": "..."},
    {"type": "text", "text": "The actual response..."},
    {"type": "tool_use", "name": "Read", "input": {...}}
  ]
}

• Filter to type: "user" and type: "assistant" entries only
• For assistant entries, extract text blocks (skip thinking and tool_use — those are noise)
• The cwd field tells you which project this conversation belongs to
• Skip type: "progress" — internal agent progress updates
• Skip type: "file-history-snapshot" — file state tracking
• Skip subagent conversations (under subagents/ subdirectories) — unless the user asks

Step 3b: Parse Audit Logs (desktop sessions only)

For each audit.jsonl found under local-agent-mode-sessions/, read it line by line. Each line is a JSON record of one agent action:

{
  "type": "tool_call",
  "toolName": "Bash",
  "input": {"command": "npm test"},
  "output": "...",
  "timestamp": "2026-04-10T14:22:00Z",
  "sessionId": "..."
}

What to extract from audit logs:

• File access patterns — which files does the agent repeatedly Read or Edit? These are the high-value files in the project. Note them as project references.
• Shell commands — recurring Bash commands reveal the project's build/test/deploy workflow. Distill these into a skills/ page (e.g. "how this project is built and tested").
• Tool call sequences — if the agent always does Read → Edit → Bash in a particular order, that's a workflow pattern worth capturing.
• Error patterns — failed tool calls (non-zero exit codes, error outputs) reveal pain points, known rough edges, or recurring bugs.
• MCP tool calls — calls to MCP tools reveal which external services and APIs the project integrates with.

Skip from audit logs:

• Routine file reads with no pattern (e.g. reading config files once)
• Tool outputs that are just noise (long stack traces, verbose logs) — summarize the error class, not the full output
• Anything that looks like secrets, tokens, or credentials in command arguments or outputs

Cross-reference with the conversation transcript: The audit log tells you what happened; the conversation tells you why. When both are available for the same session, use them together — the audit log grounds the conversation in concrete actions.

Read the paired local_<uuid>.json session metadata before processing the audit log — it gives you cwd, startedAt, and title to contextualize the actions.

Step 4: Cluster by Topic

Don't create one wiki page per conversation. Instead:

• Group extracted knowledge by topic across conversations
• A single conversation about "debugging auth + setting up CI" → two separate topics
• Three conversations across different days about "React performance" → one merged topic
• The project directory name gives you a natural first-level grouping

Step 5: Distill into Wiki Pages

Each Claude project maps to a project directory in the vault. The project directory name from ~/.claude/projects/ encodes the original path — decode it to get a clean project name:

-Users/Documents/projects/my-Project   → myproject
-Users/Documents/projects/Another-app  → anotherapp

Project-specific vs. global knowledge

For each project with content, create or update the project overview page at projects/<name>/<name>.md — named after the project, not _project.md. Obsidian's graph view uses the filename as the node label, so _project.md makes every project show up as _project in the graph. Naming it <name>.md gives each project a distinct, readable node name.

Important: Distill the knowledge, not the conversation. Don't write "In a conversation on March 15, the user asked about X." Write the knowledge itself, with the conversation as a source attribution.

Write a summary: frontmatter field on every new/updated page — 1–2 sentences, ≤200 chars, answering "what is this page about?" for a reader who hasn't opened it. wiki-query's cheap retrieval path reads this field to avoid opening page bodies.

Add confidence and lifecycle fields to every new page's frontmatter:

base_confidence: 0.42
lifecycle: draft
lifecycle_changed: <ISO date today>

On update, leave lifecycle and lifecycle_changed unchanged — only a human editor transitions lifecycle state.

Mark provenance per the convention in llm-wiki (Provenance Markers section):

• Memory files are mostly extracted — the user wrote them by hand and they're already distilled. Treat memory-derived claims as extracted unless you're stitching together claims from multiple memory files.
• Conversation distillation is mostly inferred. You're synthesizing a coherent claim from many turns of dialogue, often filling in implicit reasoning. Apply ^[inferred] liberally to synthesized patterns, generalizations across sessions, and "what the user really meant" interpretations.
• Use ^[ambiguous] when the user changed their mind across sessions or when assistant and user contradicted each other and the resolution is unclear.
• Write a provenance: frontmatter block on every new/updated page summarizing the rough mix.

Step 6: Update Manifest, Journal, and Special Files

Update .manifest.json

For each source file processed, add/update its entry with:

• ingested_at, size_bytes, modified_at
• source_type: one of "claude_conversation", "claude_memory", "claude_audit_log", "claude_desktop_session"
• project: the decoded project name
• pages_created and pages_updated lists

Also update the projects section of the manifest:

{
  "project-name": {
    "source_path": "~/.claude/projects/-Users-...",
    "vault_path": "projects/project-name",
    "last_ingested": "TIMESTAMP",
    "conversations_ingested": 5,
    "conversations_total": 8,
    "memory_files_ingested": 3,
    "desktop_sessions_ingested": 2,
    "audit_logs_ingested": 2
  }
}

Create journal entry + update special files

Update index.md and log.md per the standard process:

- [TIMESTAMP] CLAUDE_HISTORY_INGEST projects=N conversations=M desktop_sessions=D audit_logs=A pages_updated=X pages_created=Y mode=append|full

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Ingested 5 Claude conversations across 2 projects; surfaced patterns in API design and testing strategy." Keep the last 3 operations. Update Active Threads if any ongoing project is now better understood. Update the updated: field in the frontmatter to the current timestamp — this is easy to forget; the body edit and the frontmatter bump must both happen.

Privacy

• Distill and synthesize — don't copy raw conversation text verbatim
• Skip anything that looks like secrets, API keys, passwords, tokens
• If you encounter personal/sensitive content, ask the user before including it
• The user's conversations may reference other people — be thoughtful about what goes in the wiki

Reference

See references/claude-data-format.md for more details on the data structures.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Copilot History Ingest — Conversation Mining

You are extracting knowledge from the user's past GitHub Copilot CLI conversations and distilling it into the Obsidian wiki. Conversations are rich but messy — your job is to find the signal and compile it.

This skill can be invoked directly or via the wiki-history-ingest router (/wiki-history-ingest copilot).

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH, COPILOT_HISTORY_PATH (defaults to ~/.copilot/session-state), and COPILOT_VSCODE_STORAGE_PATH (VS Code workspaceStorage; platform-specific — ask the user if absent)
2. Read .manifest.json at the vault root to check what's already been ingested
3. Read index.md at the vault root to know what the wiki already contains

Ingest Modes

Append Mode (default)

Check .manifest.json for each source file (events JSONL, transcript JSONL, checkpoint, session-store DB). Only process:

• Sessions not in the manifest (new sessions)
• Sessions whose updated_at is newer than their ingested_at in the manifest

This is usually what you want — the user ran a few new sessions and wants to capture the delta.

Full Mode

Process everything regardless of manifest. Use after a wiki-rebuild or if the user explicitly asks.

GitHub Copilot Data Layout

Copilot stores data in three locations. Scan all three.

Source 1: ~/.copilot/session-state/ (CLI sessions)

~/.copilot/session-state/
├── <session-uuid>/
│   ├── workspace.yaml           # Session metadata (id, cwd, summary_count, created_at, updated_at)
│   ├── vscode.metadata.json     # VS Code context (workspaceFolder, repositoryProperties, customTitle)
│   ├── events.jsonl             # Full event log — all turns, tool calls, reasoning
│   ├── session.db               # Per-session SQLite (todos/todo_deps only — skip for ingestion)
│   ├── index.md                 # Session summary written at session end
│   ├── checkpoints/             # Checkpoint JSON files (mid-session summaries)
│   │   └── <uuid>.json          # title, overview, history, work_done, technical_details,
│   │                            #   important_files, next_steps
│   ├── files/                   # Artifacts produced during session (plans, diagrams, etc.)
│   └── research/                # Research artifacts
└── ...

Source 2: ~/.copilot/session-store.db (Global SQLite)

The canonical cross-session database. This is the highest-value source: structured, queryable, and pre-summarised.

sessions       — id, cwd, repository, branch, summary, created_at, updated_at, host_type
turns          — session_id, turn_index, user_message, assistant_response, timestamp
checkpoints    — session_id, checkpoint_number, title, overview, history, work_done,
                 technical_details, important_files, next_steps, created_at
session_files  — session_id, file_path, tool_name, turn_index, first_seen_at
session_refs   — session_id, ref_type (commit/pr/issue), ref_value, turn_index, created_at
search_index   — FTS5 virtual table (content, session_id, source_type, source_id)

Source 3: VS Code Workspace Storage (<workspaceStorage>/<hash>/GitHub.copilot-chat/)

VS Code extension data, keyed by workspace hash. The path is platform-specific and must come from .env or user input.

<hash>/GitHub.copilot-chat/
├── transcripts/
│   └── <session-uuid>.jsonl     # Conversation transcripts (same JSONL format as events.jsonl)
├── memory-tool/
│   └── memories/
│       └── <base64-session-id>/ # Per-session saved artifacts (plan.md, etc.)
│           └── plan.md
└── codebase-external.sqlite     # Codebase index (skip — no conversation knowledge)

Key data sources ranked by value:

1. Checkpoints (session-store.db checkpoints table + per-session checkpoints/*.json) — Pre-distilled summaries with overview, work_done, technical_details, important_files, next_steps. Gold.
2. Session summaries (session-store.db sessions.summary + index.md) — One-paragraph synopsis per session.
3. Turns (session-store.db turns table + events.jsonl / transcript JSONL) — Full conversation. Rich but verbose.
4. Memory artifacts (memory-tool/memories/<id>/plan.md etc.) — Pre-written plans and structured notes the user saved explicitly. Worth importing verbatim (or lightly summarised).
5. File access patterns (session_files table + tool.execution_* events) — Which files the agent repeatedly touched — reveals high-value project files.
6. Session refs (session_refs table) — Commits, PRs, and issues linked to sessions.
7. vscode.metadata.json — Workspace folder path, branch, customTitle (user-set session label). Useful for grouping and naming.

Step 1: Survey and Compute Delta

Scan all three data locations and compare against .manifest.json:

# --- Source 1: per-session directories ---
# Find all session directories (each has workspace.yaml)
ls ~/.copilot/session-state/

# For each session, read workspace.yaml for id/cwd/updated_at
# and vscode.metadata.json for customTitle / repositoryProperties

# --- Source 2: global database ---
# Query session-store.db with sqlite3 (or Python sqlite3)
SELECT s.id, s.cwd, s.repository, s.branch, s.summary, s.updated_at,
       COUNT(DISTINCT t.turn_index) AS turn_count,
       COUNT(DISTINCT c.id)         AS checkpoint_count
FROM sessions s
LEFT JOIN turns t ON t.session_id = s.id
LEFT JOIN checkpoints c ON c.session_id = s.id
GROUP BY s.id
ORDER BY s.updated_at DESC;

# --- Source 3: VS Code workspace storage ---
# For each <hash> directory under workspaceStorage, check for GitHub.copilot-chat/
# Find transcript files
ls <workspaceStorage>/<hash>/GitHub.copilot-chat/transcripts/

Build a unified inventory — one entry per session UUID — and classify:

• New — not in manifest → needs ingesting
• Modified — in manifest but updated_at is newer → needs re-ingesting
• Unchanged — in manifest and not modified → skip in append mode

Report to the user: "Found X sessions in session-state, Y in session-store.db, Z VS Code transcript files. Checkpoints: A. Delta: B new, C modified."

Step 2: Ingest Checkpoints and Summaries First

Checkpoints are already distilled — process them before touching raw turns.

From session-store.db:

SELECT s.id, s.cwd, s.repository, s.branch, s.summary,
       c.checkpoint_number, c.title, c.overview, c.work_done,
       c.technical_details, c.important_files, c.next_steps,
       c.created_at
FROM checkpoints c
JOIN sessions s ON c.session_id = s.id
ORDER BY s.updated_at DESC, c.checkpoint_number ASC;

From per-session checkpoints/*.json:

Each checkpoint file has: title, overview, history, work_done, technical_details, important_files, next_steps.

Read index.md (if present) as a session-level summary — it's typically written at session end and is already concise.

What to extract:

• overview → high-level description of what the session accomplished
• work_done → concrete tasks completed (good for skills / project pages)
• technical_details → implementation specifics (good for concepts pages)
• important_files → high-value files in the project (good for project pages)
• next_steps → open threads (good for linking to ongoing project work)

Step 3: Parse Session Turns

Read turns from session-store.db (preferred — already parsed) or from events.jsonl / transcript JSONL.

From session-store.db:

SELECT turn_index, user_message, assistant_response, timestamp
FROM turns
WHERE session_id = '<uuid>'
ORDER BY turn_index ASC;

From events.jsonl / transcript JSONL:

Each file is one session. Each line is a JSON event. See references/copilot-data-format.md for the full schema.

Relevant event types:

Extraction strategy for assistant.message:

• data.content is the assistant's text response — extract this
• data.reasoningText is internal reasoning — skip (it's the unpacked reasoningOpaque field)
• data.toolRequests lists tool calls — skim tool names and arguments for file access patterns
• Skip type: "tool.execution_end" entirely

Step 3b: Process Memory Artifacts

For each session that has a memory-tool/memories/<base64-id>/ directory in VS Code workspace storage, read any markdown files saved there (typically plan.md). These are documents the user explicitly saved — treat them as high-quality, user-authored content.

Decode the base64 directory name to get the session UUID:

import base64
session_id = base64.b64decode(dir_name).decode('utf-8')

Memory artifacts map to project skills/ or concepts/ pages, depending on content type.

Step 3c: Extract File and Ref Patterns

From session-store.db:

-- Most-touched files per project
SELECT repository, file_path, COUNT(*) AS touch_count
FROM session_files
GROUP BY repository, file_path
ORDER BY touch_count DESC;

-- Linked commits/PRs/issues per session
SELECT session_id, ref_type, ref_value, turn_index
FROM session_refs
ORDER BY session_id, turn_index;

File access patterns reveal which files are architecturally important — note them on project pages.

Session refs link Copilot sessions to git history — useful for connecting wiki knowledge to concrete code changes.

Step 4: Cluster by Topic

Don't create one wiki page per session. Instead:

• Group extracted knowledge by topic across sessions
• A single session about "debugging auth + setting up CI" → two separate topics
• Three sessions across different days about "React performance" → one merged topic
• cwd / repository give you a natural first-level grouping; vscode.metadata.json's customTitle gives a human-readable session label

Step 5: Distill into Wiki Pages

Each Copilot project maps to a project directory in the vault. Derive the project name from cwd or repository:

C:\Users\name\git\my-project   → my-project
/Users/name/code/another-app   → another-app

Prefer repository (e.g., owner/repo) from session-store.db over raw cwd when available.

Project-specific vs. global knowledge

For each project with content, create or update the project overview page at projects/<name>/<name>.md — named after the project, not _project.md. Obsidian's graph view uses the filename as the node label, so _project.md makes every project show up as _project in the graph. Naming it <name>.md gives each project a distinct, readable node name.

Important: Distill the knowledge, not the conversation. Don't write "In a session on March 15, the user asked about X." Write the knowledge itself, with the session as a source attribution.

Write a summary: frontmatter field on every new/updated page — 1–2 sentences, ≤200 chars, answering "what is this page about?" for a reader who hasn't opened it. wiki-query's cheap retrieval path reads this field to avoid opening page bodies.

Add confidence and lifecycle fields to every new page's frontmatter:

base_confidence: 0.42
lifecycle: draft
lifecycle_changed: <ISO date today>

Leave lifecycle unchanged on update.

Mark provenance per the convention in llm-wiki (Provenance Markers section):

• Checkpoints and index.md are pre-distilled by the system — treat checkpoint-derived claims as extracted (the system wrote them from observed actions).
• Memory artifacts are user-authored — treat as extracted.
• Conversation turn distillation is mostly inferred. You're synthesizing a coherent claim from many turns. Apply ^[inferred] liberally to synthesized patterns, generalizations across sessions, and "what the user really meant" interpretations.
• Use ^[ambiguous] when the user changed direction mid-session or when the session ended unresolved.
• Write a provenance: frontmatter block on every new/updated page summarizing the rough mix.

Step 6: Update Manifest, Journal, and Special Files

Update .manifest.json

For each session processed, add/update its entry with:

• ingested_at, session_id, updated_at
• source_type: one of "copilot_session", "copilot_checkpoint", "copilot_transcript", "copilot_memory_artifact"
• project: the decoded project name
• pages_created and pages_updated lists

Also update the projects section of the manifest:

{
  "project-name": {
    "repository": "owner/repo",
    "cwd": "C:\\Users\\name\\git\\project-name",
    "vault_path": "projects/project-name",
    "last_ingested": "TIMESTAMP",
    "sessions_ingested": 5,
    "sessions_total": 8,
    "checkpoints_ingested": 12,
    "memory_artifacts_ingested": 3
  }
}

Create journal entry + update special files

Update index.md and log.md per the standard process:

- [TIMESTAMP] COPILOT_HISTORY_INGEST projects=N sessions=M checkpoints=C pages_updated=X pages_created=Y mode=append|full

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Ingested 5 Copilot sessions across 2 projects; surfaced patterns in API design and testing strategy." Keep the last 3 operations. Update Active Threads if any ongoing project is now better understood. Update updated timestamp.

Privacy

• Distill and synthesize — don't copy raw conversation text verbatim
• Skip anything that looks like secrets, API keys, passwords, tokens
• data.reasoningOpaque / data.reasoningText in assistant events is internal reasoning — skip entirely, never copy to wiki
• If you encounter personal/sensitive content, ask the user before including it
• The user's conversations may reference other people — be thoughtful about what goes in the wiki

Reference

See references/copilot-data-format.md for detailed data structure documentation.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Cross-Linker — Automated Wiki Cross-Referencing

You are weaving the wiki's knowledge graph tighter by finding and inserting missing [[wikilinks]] between pages that should reference each other but currently don't.

Follow the Retrieval Primitives table in llm-wiki/SKILL.md. Build the registry in Step 1 by grepping frontmatter only (not full pages). Reserve full Read for the unlinked-mention detection pass, and even there, only read pages whose summaries/titles make them plausible link targets. Blind full-vault reads are what this framework exists to avoid.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH and OBSIDIAN_LINK_FORMAT (default: wikilink).
2. Read index.md to get the full inventory of pages and their one-line descriptions
3. Skim log.md to see what was recently ingested (focus linking effort on new pages)

When inserting links in Step 4, apply the link format from llm-wiki/SKILL.md (Link Format section) using the OBSIDIAN_LINK_FORMAT value. When OBSIDIAN_LINK_FORMAT=markdown, compute the relative .md path from the file being edited to the target page.

Step 1: Build the Page Registry

Glob all .md files in the vault (excluding _archives/, .obsidian/). For each page, extract:

• Filename (without .md) — this is the wikilink target
• Title from frontmatter
• Aliases from frontmatter (if any)
• Tags from frontmatter
• Category from frontmatter or directory inference
• One-line summary — first sentence or title field

Build a lookup table:

page_name → { path, title, aliases, tags, summary }

This is your "vocabulary" — every entry in this table is a valid wikilink target.

Step 2: Scan for Missing Links

For each page in the vault:

1. Read the full content

2. Extract existing wikilinks — find all [[...]] references already present

3. Search for unlinked mentions — check if the page's text contains any of these, without being wrapped in [[...]]:

   • Page filenames (e.g., the word "MyProject" appears but [[projects/my-project/my-project]] is missing)
   • Page titles from frontmatter
   • Aliases from frontmatter
   • Entity names, project names, concept names from the registry

4. Check for semantic connections — pages that share multiple tags or are in the same project directory but don't link to each other

Matching Rules

• Case-insensitive matching for names (e.g., "my-project" matches page MyProject)
• Diacritic-insensitive matching — normalize both the page name and the body text with Unicode NFKD (decompose accented characters to base + combining marks, strip combining marks) before comparing. This ensures body text "Muller" matches page [[entities/müller]] and vice versa.
• Skip self-references — a page shouldn't link to itself
• Skip common words — don't link "the", "and", generic terms. Only match on distinctive names
• Prefer the shortest unambiguous wikilink path — use [[page-name]] not [[full/path/to/page-name]] when the name is unique across the vault
• Don't link inside code blocks or frontmatter
• Don't double-link — if [[foo]] already appears on the page, don't add another

Step 3: Score and Rank Suggestions

Not every possible link is worth adding. Score each candidate using a composite signal, then tag it with a confidence label.

Scoring

Confidence labels

Tag each candidate with a confidence label based on its score:

Only act on EXTRACTED and INFERRED candidates. Include the confidence label in the Cross-Link Report so the user can review INFERRED links before trusting them.

Step 4: Apply Links

For each page with missing links:

4a: Inline linking (preferred)

Find the first natural mention of the term in the body text and wrap it in wikilinks:

Before:

This project uses knowledge graphs to connect entities.

After:

This project uses [[concepts/knowledge-graphs|knowledge graphs]] to connect entities.

Use the [[path|display text]] format when the wikilink path differs from the display text.

4b: Related section (fallback)

If the term isn't mentioned naturally in the body but the pages are semantically related (shared tags, same project), add a ## Related section at the bottom of the page:

## Related

- [[projects/my-project/my-project]] — Also uses AI agents for research automation
- [[concepts/knowledge-graphs]] — Core technique used in this project

If a ## Related section already exists, append to it. Don't duplicate existing entries.

4c: Infer and write relationship type

For every EXTRACTED or INFERRED link added (inline or related section), infer a semantic relationship type from the surrounding sentence context and write it to the page's relationships: frontmatter block. Skip AMBIGUOUS links.

Type inference rules — scan the sentence containing the mention (or, for related-section links, the page title and shared-tag context):

If the surrounding context is ambiguous or the link came from shared-tag matching (no in-body mention), default to related_to.

Writing the block:

Read the page's YAML frontmatter. If a relationships: block already exists, append new entries without duplicating existing targets. If the block is absent, add it after aliases: (or after tags: when aliases: is missing).

relationships:
  - target: "[[concepts/knowledge-graphs]]"
    type: uses

Always use wikilink format ([[path/to/page]]) for target values in the relationships: YAML block — regardless of OBSIDIAN_LINK_FORMAT. The OBSIDIAN_LINK_FORMAT setting controls body content; frontmatter properties always use wikilink syntax so that wiki-export can reliably parse them.

Only add entries for links added in this cross-linker run — do not touch typed entries that were already present.

Step 5: Score Misc Page Affinity

After the main linking pass, update affinity scores for all pages in misc/ (pages with promotion_status: misc in their frontmatter, or located under the misc/ directory).

For each misc page:

1. Collect outgoing links — all [[wikilinks]] in the page body
2. Collect incoming links — grep the vault for [[misc/<slug>]] and [[<slug>]] references
3. For each linked page (both directions), check if it belongs to a project:
   • Lives under projects/<project-name>/
   • Has a project: frontmatter field matching a project name
4. Group by project name and sum: outgoing_links + incoming_links
5. Update the affinity frontmatter block on the misc page:

affinity:
  obsidian-wiki: 3
  another-project: 1

6. If any project's score ≥ 3: flag this page as a promotion candidate and record it for the report

Efficiency note: only read the full body of misc pages — other pages only need a frontmatter grep to determine their project membership.

Step 6: Report

Present a summary:

## Cross-Link Report

### Links Added: 23 across 12 pages

| Page | Links Added | Confidence | Placement | Relationship Types |
|---|---|---|---|---|
| `projects/my-project/my-project.md` | 3 | EXTRACTED | 2 inline, 1 related | uses ×2, related_to ×1 |
| `entities/jane-doe.md` | 5 | INFERRED | 3 inline, 2 related | extends ×1, uses ×3, related_to ×1 |
| ... | | | | |

### Orphan Pages Remaining: 2
- `references/foo.md` — no incoming or outgoing links found
- `concepts/bar.md` — could not find related pages

### Misc Promotion Candidates: N
Pages in misc/ that have ≥ 3 connections to a single project — ready to be promoted:

| Page | Top Project | Score |
|---|---|---|
| `misc/web-martinfowler-articles-microservices.md` | `obsidian-wiki` | 4 |

To promote: move the page to `projects/<project-name>/references/` and update all backlinks.

### Pages Skipped: 3
- `index.md`, `log.md` — special files
- `_archives/*` — archived content

Step 7: Update Log and Hot Cache

Append to log.md:

- [TIMESTAMP] CROSS_LINK pages_scanned=N links_added=M typed_relations_written=T pages_modified=P orphans_remaining=Q misc_affinity_updated=R promotion_candidates=S

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary of what was linked — e.g. "Cross-linked 23 mentions across 12 pages; 2 orphans remain." Keep the last 3 operations. Update updated timestamp.

Tips

• Run after every ingest. New pages are almost always poorly connected. This is the fix.
• Be conservative with inline links. Only link the first natural mention, not every occurrence.
• Don't touch pages in _archives/. Those are frozen snapshots.
• Respect existing structure. If a page carefully curates its links in a ## Key Concepts section, add to that section rather than creating a separate ## Related.
• Entity pages are link magnets. An entity like jane-doe should be linked from almost every project page. Prioritize these.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Graph Colorize — Color-code the Obsidian Graph View

You are rewriting $OBSIDIAN_VAULT_PATH/.obsidian/graph.json so Obsidian's graph view tints nodes by tag, folder, or visibility.

Obsidian stores graph settings in <vault>/.obsidian/graph.json. The colorGroups array is a list of {query, color} pairs; the first matching query wins per node. Queries use Obsidian's search syntax: tag:#foo, path:"concepts", file:foo, etc. Color is {"a": 1, "rgb": <packed-int>} where the int is (R << 16) | (G << 8) | B.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH.
2. Confirm $OBSIDIAN_VAULT_PATH/.obsidian/ exists. If it doesn't, the vault has never been opened in Obsidian — tell the user to open the vault once in Obsidian, then re-run.
3. Warn the user if Obsidian is likely open: Obsidian overwrites graph.json on close. Tell them to close the vault first, or be ready to reload (Cmd/Ctrl+R) and not touch the graph settings until they reload.

Step 1: Pick a Mode

Infer the mode from the user's phrasing. If ambiguous, default to by-tag.

Step 2: Build the colorGroups Array

Palette (10 distinct, colorblind-friendly colors)

Use in order. If more groups than colors, cycle and add a lightness shift by dividing brightness ~20% via a second pass — or just cap at 10 and tell the user the remaining tags share the "other" color.

Every color is wrapped as {"a": 1, "rgb": <int>}.

Mode: by-tag

1. Glob $VAULT_PATH/**/*.md excluding _archives/, _raw/, .obsidian/, node_modules/, index.md, log.md, _insights.md.
2. Parse frontmatter tags from each page. Count usage per tag.
3. Drop visibility/* tags from the frequency list — they are reserved system tags, handled only in by-visibility or combined mode.
4. Take the top 10 tags by usage. If there are fewer than 10 unique tags, use all of them.
5. For each tag T at index i: emit {"query": "tag:#T", "color": palette[i]}.
6. Optionally, append a final catch-all entry for untagged pages at the end: {"query": "-[\"tag\":]", "color": palette[9]} — skip if color slot 9 is already taken by a real tag.

Mode: by-category

Use the seven vault top-level folders in this fixed order so colors are stable across runs:

Emit one entry per folder that exists AND contains at least one .md file. Each entry is:

{"query": "path:\"<folder>\"", "color": {"a": 1, "rgb": <int>}}

Mode: by-visibility

Emit exactly three entries, in this order (first-match wins, so most restrictive comes first):

1. visibility/pii → #E15759 (red, rgb 14767961)
2. visibility/internal → #F28E2B (orange, rgb 15896107)
3. visibility/public → #59A14F (green, rgb 5873999)

{"query": "tag:#visibility/pii", "color": {"a": 1, "rgb": 14767961}}

Pages with no visibility/ tag remain Obsidian's default color — do not add a catch-all.

Mode: combined

Emit by-visibility entries first, then by-tag entries. Visibility wins on conflict because it appears first in the list.

Mode: custom

If the user gave explicit mappings, honor them literally. Convert any hex they give (e.g. #FF00FF) to packed int using int(hex_without_hash, 16). Wrap each as {"a": 1, "rgb": <int>}.

Step 3: Merge into graph.json (Do Not Clobber)

1. Read the existing $VAULT_PATH/.obsidian/graph.json. If it doesn't exist, start from this minimal default:

   {
     "collapse-filter": true,
     "search": "",
     "showTags": false,
     "showAttachments": false,
     "hideUnresolved": false,
     "showOrphans": true,
     "collapse-color-groups": false,
     "colorGroups": [],
     "collapse-display": true,
     "showArrow": false,
     "textFadeMultiplier": 0,
     "nodeSizeMultiplier": 1,
     "lineSizeMultiplier": 1,
     "collapse-forces": true,
     "centerStrength": 0.518713248970312,
     "repelStrength": 10,
     "linkStrength": 1,
     "linkDistance": 250,
     "scale": 1,
     "close": true
   }
   

2. Back up first: copy the existing file to .obsidian/graph.json.backup-<YYYYMMDD-HHMM> before writing. If a backup from the same minute exists, reuse it — don't pile up duplicates.

3. Replace only the colorGroups field with your new array. Leave every other field untouched. This preserves the user's zoom, physics, filter, search, and display preferences.

4. Write the file back with the same JSON style as the original (usually compact single-line or 2-space indent — preserve what's there).

Step 4: Report and Log

Print a summary like:

Graph colorized → .obsidian/graph.json
  Mode:    by-tag
  Groups:  7 color assignments
  Palette: blue, orange, red, teal, green, yellow, purple
  Backup:  .obsidian/graph.json.backup-20260424-1432

Reload Obsidian (Cmd/Ctrl+R) to see the new colors.
If Obsidian is currently open, close it first OR reload immediately — Obsidian
overwrites graph.json on close and can erase these changes.

Append to $VAULT_PATH/log.md:

- [TIMESTAMP] GRAPH_COLORIZE mode=<mode> groups=<N> backup=graph.json.backup-<stamp>

Edge Cases

• No tags in vault in by-tag mode → fall back to by-category and tell the user.
• User wants to undo → restore from the latest graph.json.backup-* and note that in log.md.
• User wants to clear all color groups → set colorGroups: [], back up, log as GRAPH_COLORIZE mode=clear.
• .obsidian/ missing → the vault hasn't been opened in Obsidian yet. Tell the user to open it once, then re-run. Don't create .obsidian/ yourself — Obsidian populates many files there on first open.
• Query syntax gotchas: folder paths with spaces need quoting (path:"my folder"); tags with nested slashes work literally (tag:#visibility/internal); don't URL-encode.
• Obsidian open during edit: surface the risk — Obsidian reads graph.json at startup and rewrites it on close. If the user is editing live, tell them to close Obsidian first or run the reload (Cmd/Ctrl+R) immediately and avoid opening graph settings before they do.

Notes

• This is a pure config edit — no page content changes, no frontmatter writes.
• Re-running is safe: each run creates a new backup, only colorGroups is rewritten.
• If the user has manually curated color groups they want to keep, offer combined mode or ask before overwriting.
• The palette here matches wiki-export's graph.html community colors, so the Obsidian graph and the exported visualization look consistent.

Implementation Validator — Quality Subagent

You are a critical reviewer. Another skill or agent has just done work and wants you to check it. Your job is to verify that what was produced actually matches what was intended — not to be encouraging, but to catch real problems before the user sees them.

This skill runs in two modes:

1. Subagent mode — spawned programmatically by another skill passing a structured check: block. Read the block, run the checks, return structured output.
2. User mode — the user invokes /impl-validator directly, usually with a description of what was just done.

Input Format (Subagent Mode)

When spawned by another skill, you receive a block like:

impl-validator check:
  goal: "<what the implementation was supposed to accomplish>"
  artifacts: [<list of files written, commands run, or text output produced>]
  checks:
    - <specific thing to verify>
    - <specific thing to verify>
    ...

Parse this block and treat each field as your mandate.

Input Format (User Mode)

The user describes what was just done. Infer the goal and artifacts from context. Ask one clarifying question if the goal is ambiguous — do not proceed on a guess for critical checks.

Validation Protocol

Step 1: Understand the Goal

Restate the goal in one sentence. If you can't, the goal is underspecified — flag this as a WARN.

Step 2: Check Each Artifact

For each artifact (file, output, config):

1. Existence check — does the file/output actually exist? Read it.
2. Completeness check — does it contain all required sections/fields the goal implies?
3. Correctness check — does the content logically match the stated goal? Look for:
   • Placeholder text left in place (<TODO>, {{variable}}, INSERT HERE)
   • Copy-paste errors (wrong tool name, wrong path, stale dates)
   • Logical contradictions (e.g. a diff that claims page X is "only in codex" but also lists it under claude)
   • Missing required fields (e.g. a SKILL.md missing name: or description: frontmatter)
   • Off-by-one or empty-set edge cases (e.g. page count = 0 when vault is known non-empty)
4. Convention check — does it follow the project's established patterns?
   • Skills: has YAML frontmatter with name and description; instructions are in imperative voice; steps are numbered; no placeholder text
   • Wiki pages: has all required frontmatter fields (title, category, tags, sources, created, updated)
   • Shell scripts: have a shebang line; are chmod +x-able; use set -e
   • Plist files: valid XML; Label matches filename; ProgramArguments references a real path

Step 3: Run the Provided Checks

For each check in the checks: list, evaluate it explicitly. Don't skip. Answer each with:

• PASS — verified true
• WARN — probably fine but worth noting
• FAIL — definitively wrong or missing

Step 4: Produce Verdict

## impl-validator Report

**Goal:** <restated goal>

### Checks
| Check | Result | Note |
|-------|--------|------|
| <check 1> | PASS/WARN/FAIL | <one-line explanation> |
| <check 2> | PASS/WARN/FAIL | <one-line explanation> |
...

### Overall: PASS / WARN / FAIL

**Issues to fix (FAIL):**
- <specific issue with file path and line if applicable>

**Worth noting (WARN):**
- <non-blocking observation>

Overall verdict rules:

• Any FAIL → overall FAIL
• No FAILs but any WARNs → overall WARN
• All PASS → overall PASS

Step 5: Return to Caller

In subagent mode: return the full report as your response. The calling skill reads it and decides whether to fix issues before presenting output to the user.

In user mode: present the report directly. If overall FAIL, offer to fix the issues.

What NOT to check

• Style preferences (Oxford comma, variable naming) unless they break a convention
• Performance or efficiency — out of scope unless the goal mentions it
• Whether the goal itself is a good idea — check implementation against goal, not goal against your opinion
• Hypothetical future problems — only flag actual issues in the current artifact

Severity Guide

LLM Wiki — Knowledge Distillation Pattern

You are maintaining a persistent, compounding knowledge base. The wiki is not a chatbot — it is a compiled artifact where knowledge is distilled once and kept current, not re-derived on every query.

Three-Layer Architecture

Layer 1: Raw Sources (immutable)

The user's original documents — articles, papers, notes, PDFs, conversation logs, bookmarks, and images (screenshots, whiteboard photos, diagrams, slide captures). These are never modified by the system. They live wherever the user keeps them (configured via OBSIDIAN_SOURCES_DIR in .env). Images are first-class sources: the ingest skills read them via the Read tool's vision support and treat their interpreted content as inferred unless it's verbatim transcribed text. Image ingestion requires a vision-capable model — models without vision support should skip image sources and report which files were skipped.

Think of raw sources as the "source code" — authoritative but hard to query directly.

Don't confuse this with the in-vault _raw/ staging folder, which is a different thing: a scratch inbox for quick captures and drafts awaiting promotion (see wiki-capture and wiki-ingest). Files there aren't Layer 1 sources, but wiki-ingest still moves rather than deletes them on promotion, since some have no other copy.

Layer 2: The Wiki (LLM-maintained)

A collection of interconnected Obsidian-compatible markdown files organized by category. This is the compiled knowledge — synthesized, cross-referenced, and navigable. Each page has:

• YAML frontmatter (title, category, tags, sources, timestamps)
• Obsidian [[wikilinks]] connecting related concepts
• Clear provenance — every claim traces back to a source

The wiki lives at the path configured via OBSIDIAN_VAULT_PATH in .env.

Layer 3: The Schema (this skill + config)

The rules governing how the wiki is structured — categories, conventions, page templates, and operational workflows. The schema tells the LLM how to maintain the wiki.

Wiki Organization

The vault has two levels of structure: categories (what kind of knowledge) and projects (where the knowledge came from).

Categories

Organize pages into these default categories (customizable in .env):

Projects

Knowledge often belongs to a specific project. The projects/ directory mirrors this:

$OBSIDIAN_VAULT_PATH/
├── projects/
│   ├── my-project/
│   │   ├── my-project.md      ← project overview (named after project)
│   │   ├── concepts/          ← project-scoped category pages
│   │   ├── skills/
│   │   └── ...
│   ├── another-project/
│   │   └── ...
│   └── side-project/
│       └── ...
├── concepts/                   ← global (cross-project) knowledge
├── entities/
├── skills/
└── ...

When knowledge is project-specific (a debugging technique that only applies to one codebase, a project-specific architecture decision), put it under projects/<project-name>/<category>/.

When knowledge is general (a concept like "React Server Components", a person like "Andrej Karpathy", a widely applicable skill), put it in the global category directory.

Cross-referencing: Project pages should [[wikilink]] to global pages and vice versa. A project's overview page should link to the key concept, skill, and entity pages relevant to that project — whether they live under the project or globally.

Naming rule: The project overview file must be named <project-name>.md, not _project.md. Obsidian's graph view uses the filename as the node label — _project.md makes every project appear as _project in the graph, making it unreadable. So projects/my-project/my-project.md, projects/another-project/another-project.md, etc.

Each project directory has an overview page structured like this:

---
title: My Project
category: project
tags: [ai, web, backend]
source_path: ~/.claude/projects/-Users-name-Documents-projects-my-project
created: 2026-03-01T00:00:00Z
updated: 2026-04-06T00:00:00Z
---

# My Project

One-paragraph summary of what this project is.

## Key Concepts
- [[concepts/some-api]] — used for core functionality
- [[projects/my-project/concepts/main-architecture]] — project-specific architecture

## Related
- [[entities/some-service]] — deployment platform

Special Files

Every wiki has these files at its root:

index.md

A content-oriented catalog organized by category. Each entry has a one-line summary and tags. Rebuild this after every ingest operation. Format:

# Wiki Index

## Concepts
- [[transformer-architecture]] — The dominant architecture for sequence modeling ( #ml #architecture)
- [[attention-mechanism]] — Core building block of transformers ( #ml #fundamentals)

## Entities
- [[andrej-karpathy]] — AI researcher, educator, former Tesla AI director ( #person #ml)

Format rule: Add a space after the opening ( and tags. ❌ Don't: description (#tag) — breaks tag parsing ✅ Do: description ( #tag) — proper spacing and tag parsing

log.md

Chronological append-only record tracking every operation. Each entry is parseable:

## Log

- [2024-03-15T10:30:00Z] INGEST source="papers/attention.pdf" pages_updated=12 pages_created=3
- [2024-03-15T11:00:00Z] QUERY query="How do transformers handle long sequences?" result_pages=4
- [2024-03-16T09:00:00Z] LINT issues_found=2 orphans=1 contradictions=1
- [2024-03-17T10:00:00Z] ARCHIVE reason="rebuild" pages=87 destination="_archives/..."
- [2024-03-17T10:05:00Z] REBUILD archived_to="_archives/..." previous_pages=87

.manifest.json

Tracks every source file that has been ingested — path, timestamps, what wiki pages it produced. This is the backbone of the delta system. See the wiki-status skill for the full schema.

The manifest enables:

• Delta computation — what's new or modified since last ingest
• Append mode — only process the delta, not everything
• Audit — which source produced which wiki page
• Staleness detection — source changed but wiki page hasn't been updated

Canonical source keys. Source keys MUST be stored in a single canonical form: absolute paths with ~ and env vars expanded (e.g. /Users/me/.claude/projects/.../abc.jsonl, never ~/.claude/...). The manifest is keyed by the raw string, so a mix of ~-relative and absolute keys lets the same file be tracked twice — and the delta check then re-ingests an already-processed file because the lookup misses the other-form key. Always expand before you compare against the manifest and before you write a new entry. To repair an existing vault that already has both forms, run scripts/manifest.py normalize <vault> (merges colliding entries, keeps the newest ingested_at).

Recording provenance. When you write a manifest entry, populate pages_created and pages_updated with the vault-relative page paths that source contributed to. This is what makes re-ingestion (when a source changes) able to find the pages to revisit, instead of guessing.

Page Template

When creating a new wiki page, use this structure:

---
title: Page Title
category: concepts
tags: [ml, architecture]
aliases: [alternate name]
relationships:
  - target: "[[concepts/related-concept]]"
    type: extends
sources: [papers/attention.pdf]
summary: One or two sentences, ≤200 chars, so a reader (or another skill) can preview this page without opening it.
provenance:
  extracted: 0.72
  inferred: 0.25
  ambiguous: 0.03
base_confidence: 0.65
lifecycle: draft
lifecycle_changed: 2024-03-15
tier: supporting
created: 2024-03-15T10:30:00Z
updated: 2024-03-15T10:30:00Z
---

# Page Title

One-paragraph summary of what this page covers.

## Key Ideas

- The source's central claim, paraphrased directly.
- A generalization the source implies but doesn't state outright. ^[inferred]
- A figure two sources disagree on. ^[ambiguous]

Use [[wikilinks]] to connect to related pages.

## Open Questions

Things that are unresolved or need more sources.

## Sources

- [[references/attention-is-all-you-need]] — Original paper

Paper Deep-Dive Template

The generic template suits most sources. Academic papers are the exception. For ML/AI/LLM/VLM (and similar) papers landing in references/, the substance lives in the architecture, the equations, and the results table — exactly what a terse "Key Ideas" list flattens away. For these, use the richer template below. This is the one place where "compile, don't retrieve" yields to a thorough, self-contained walkthrough a reader could study instead of the paper.

Obsidian renders the needed primitives natively, so no extra tooling is required: Mermaid fenced diagrams, $$…$$ LaTeX (MathJax), markdown tables, and ![[image]] / ![[paper.pdf#page=N]] embeds.

Use this template only when the source is an academic paper (arXiv/conference) with load-bearing figures or equations. Everything else uses the generic Page Template above. Frontmatter, provenance markers, confidence, lifecycle, and relationships: are unchanged — only the body sections differ.

---
# ...required frontmatter, same as the generic template; category: references...
---

# Paper Title

> [!tldr] One sentence: what's new, plus the headline result.

## Problem & Motivation

What's broken or missing that this paper addresses.

## Method / Architecture

Prose walkthrough. Embed the paper's real architecture figure as the primary
visual (see *Academic papers* in `wiki-ingest` for the PyMuPDF extraction recipe).
Fall back to a Mermaid flowchart only when no figure can be extracted.

![[attachments/<slug>-fig1.png]]
*Figure N (Author Year): one-line caption.*

## Key Equations

The 1–3 core equations as display math, not backtick code:

$$ \mathcal{L} = \mathbb{E}_{x}\!\left[-\log p_\theta(y \mid z)\right] $$

## Results

Headline numbers as a table, not a comma-separated blob — and embed a key
results/motivating figure (scaling plot, benchmark chart, capability collage)
when the paper has one:

| Method | Benchmark | Metric | Cost |
|---|---|---|---|
| Baseline | … | … | … |
| **This paper** | … | … | … |

![[attachments/<slug>-resultsN.png]]
*Figure N (Author Year): one-line caption.*

## Limitations

What the paper concedes or sidesteps. Mark reading-between-the-lines as ^[inferred].

## Related

Typed `[[wikilinks]]` to neighbouring work.

## Sources

- Clickable canonical link, e.g. <https://arxiv.org/abs/XXXX.XXXXX>

A Mermaid diagram reconstructed from the paper's prose is a synthesis, not a transcription — treat it as ^[inferred] when the interpretation is non-trivial.

Provenance Markers

Every claim on a wiki page has one of three provenance states. Mark them inline so the reader (and future ingest passes) can tell signal from synthesis.

Example:

- Transformers parallelize across positions, unlike RNNs.
- This is why they scale better on modern hardware. ^[inferred]
- GPT-4 was trained on roughly 13T tokens. ^[ambiguous]

Why this syntax:

• ^[...] is footnote-adjacent in Obsidian — renders cleanly and never collides with [[wikilinks]].
• Inline (suffix) so a single bullet stays a single bullet.
• Default = extracted means existing pages without markers stay valid.

Frontmatter summary: Optionally surface the rough mix at the page level so the user can scan for speculation-heavy pages without reading them:

provenance:
  extracted: 0.72   # rough fraction of sentences/bullets with no marker
  inferred: 0.25
  ambiguous: 0.03

These are best-effort numbers written by the ingest skill at create/update time. wiki-lint recomputes them and flags drift. The block is optional — pages without it are treated as fully extracted by convention.

Typed Relationships

Plain [[wikilinks]] in page bodies carry no semantic weight — they indicate "related to" but not how. The optional relationships: frontmatter block adds typed, directional edges to the knowledge graph.

The relationships: block

relationships:
  - target: "[[Transformer Architecture]]"
    type: extends
  - target: "[[LSTM]]"
    type: contradicts
  - target: "[[Attention Mechanism]]"
    type: implements

Each entry has two required fields:

• target — a wikilink (using the same format as OBSIDIAN_LINK_FORMAT) to the related page
• type — one of the allowed semantic types below

Allowed relationship types

Rules

• Optional field — omit the block entirely if no typed relationships are known. Untagged wikilinks remain valid and are treated as related_to by wiki-export.
• Don't duplicate — if [[foo]] already appears as an inline wikilink, the relationships: entry just enriches it with a type; it is not a second link.
• Direction matters — the page declaring the entry is the source; target is the destination. Only declare relationships from this page's perspective.
• Don't fabricate — only add a typed entry when the source material makes the relationship direction and type clear. When in doubt, use related_to or omit.

Skills that read relationships:: wiki-export (emits typed edges), cross-linker (writes typed entries when inferring links), wiki-query (surfaces type in answers and walks the typed-edge graph for multi-hop "how is X connected to Y" path queries — bounded BFS over the relationships: adjacency, frontmatter-only).

Confidence and Lifecycle

Every page carries two orthogonal trust signals plus an optional supersession link.

Required fields

base_confidence: 0.65          # [0.0, 1.0] — time-independent quality estimate. Stored once, recomputed on content change.
lifecycle: draft               # draft | reviewed | verified | disputed | archived
lifecycle_changed: 2024-03-15  # ISO date of last state transition
# lifecycle_reason: "..."      # optional free-text — why the state changed; surfaced by wiki-query
# superseded_by: "[[new-page]]" # wikilink; only when lifecycle=archived

lifecycle_reason and superseded_by are optional. Never fabricate them.

Confidence formula

base_confidence = source_count_score * 0.5 + source_quality_score * 0.5

source_count_score   = min(distinct_source_ids / 3, 1.0)
source_quality_score = avg(quality score per distinct source_id)

Source-quality scores (use the highest-matching bucket):

A source_id is a stable per-source identifier — prevents counting three copies of the same blog as three distinct sources:

Per-skill defaults (ingest skills compute this automatically):

Lifecycle state machine

Five states. stale is not a state — it is a computed overlay: is_stale = (today − updated) > 90 days.

Only ingest skills set draft. All other transitions require a human editor. Update lifecycle_changed whenever the state changes.

Importance Tiering

The tier: field controls which pages get updated on each ingest pass and their priority in retrieval. As wikis grow, re-reading every page on every ingest wastes tokens — tiering lets ingest and query skills focus effort where it matters most.

Three tiers

Assignment rules

• New pages: default to tier: supporting
• Promote to core: when a page accumulates ≥5 incoming wikilinks or is flagged as a bridge by wiki-status insights mode
• Demote to peripheral: when a page has ≤1 incoming link and hasn't been updated in 90+ days
• Human override always wins — edit tier: manually to lock a page at any level
• Existing pages without tier: are treated as supporting (backward compatible — no migration needed)

Who manages tier

• wiki-ingest reads tier: to decide whether to update a page on the current pass
• wiki-query uses tier: to order candidates in the index pass and trim to context budget
• wiki-status insights mode computes graph metrics and suggests tier assignments — it never writes them automatically
• wiki-lint flags missing tier: on newly created pages (Phase 2 enforcement, same timeline as base_confidence)

Retrieval Primitives

Reading the vault is the dominant cost of every read-side skill. Use the cheapest primitive that can answer the question and escalate only when the cheaper one is insufficient. Any skill that needs content from the vault should follow this table rather than jumping straight to full-page reads.

The rule: escalate only when the cheaper primitive can't answer the question. If you can answer from summary: fields alone, don't read page bodies. If a grepped section with -A 10 -B 2 gives you the claim, don't read the whole page. A 500-line page opened to read 15 lines is 485 lines of wasted tokens.

Why this matters: a 20-page vault lets you get away with full-vault scans. A 200-page vault does not. The primitives above are how the skills framework scales to large vaults without a database.

Skills that consume this table: wiki-query, cross-linker, wiki-lint, wiki-status (insights mode). Any new skill that reads the vault should cite this section rather than reinvent the pattern.

QMD Index Freshness

QMD is an optional search index layered on top of the vault. The markdown vault is the source of truth. Any skill that writes wiki markdown should refresh QMD after the vault write completes, but only when QMD_WIKI_COLLECTION is configured and the local QMD transport is available. If QMD refresh fails, keep the vault changes and report the QMD status separately.

Use the cheapest verification path that proves the new content is visible: qmd update, qmd embed only if vectors are stale or missing, then a targeted qmd get or qmd ls check for one written page or the collection root. Read-only skills should not refresh QMD.

Core Principles

1. Compile, don't retrieve. The wiki is pre-compiled knowledge. When you ingest a source, update every relevant page — don't just create a summary of the source.

2. Compound over time. Each ingest should make the wiki smarter, not just bigger. Merge new information into existing pages, resolve contradictions, strengthen cross-references.

3. Provenance matters. Every claim should trace to a source. When updating a page, note which source prompted the update.

4. Mark inferences. Default sentences are extracted. Mark synthesized claims with ^[inferred] and contested claims with ^[ambiguous]. A wiki that hides its guessing rots silently; one that marks it stays trustworthy.

5. Human curates, LLM maintains. The human decides what sources to add and what questions to ask. The LLM handles the bookkeeping — updating cross-references, maintaining consistency, noting contradictions.

6. Obsidian is the IDE. The user browses and explores the wiki in Obsidian. Everything must be valid Obsidian markdown with working wikilinks.

Link Format

All internal links connecting wiki pages are controlled by OBSIDIAN_LINK_FORMAT from the resolved config (default: wikilink).

Generating markdown-format links

When OBSIDIAN_LINK_FORMAT=markdown:

1. Compute the path from the current file's directory to the target .md file using .. to climb up as needed.
2. Use the page title or a natural phrase as display text.
3. Always include the .md extension.

The [[path\|display text]] wikilink form maps to [display text](relative/path.md) in Markdown mode.

Scope: this setting affects only newly written or updated links. Existing vault content is never automatically migrated — users who want to convert old links can run the cross-linker or wiki-lint skill.

Every write skill reads OBSIDIAN_LINK_FORMAT from config before generating links and applies the correct format.

Config Resolution Protocol

All skills must resolve config using this algorithm — do not hard-code .env or ~/.obsidian-wiki/config directly. This ensures single-vault, multi-vault, project-local, and VPS setups all work correctly.

Resolution order

0. Inline vault override (@name) — if the user's request contains an @<name> token (e.g. @work save this, query @personal about X), resolve ~/.obsidian-wiki/config.<name> directly and use its OBSIDIAN_VAULT_PATH. This overrides both the CWD .env walk-up and the active symlink, and applies to that invocation only — never run ln -sf or otherwise change the active vault for an @name request. If ~/.obsidian-wiki/config.<name> doesn't exist, tell the user it doesn't exist and list the available vaults (the wiki-switch List logic), then stop — do not silently fall back to the default. The @name is a routing directive, not content: strip it out before treating the rest of the request as the actual instruction or page text.
1. Walk up from CWD — look for a .env file in the current directory, then each parent, up to $HOME. Stop at the first .env that contains OBSIDIAN_VAULT_PATH.
2. Global config — if no local .env found, read ~/.obsidian-wiki/config.
3. Prompt setup — if neither exists, tell the user: "No config found. Run wiki-setup to initialize your wiki."

@name is a per-invocation override — it targets one vault for one request. /wiki-switch <name> is the persistent default — it re-points the active symlink for all future requests. Use @name to touch the other vault from anywhere without disturbing your default ("brain") vault.

find_config() {
  # $1 = parsed @name from the request, if any (else empty)
  if [[ -n "$1" ]]; then
    [[ -f "$HOME/.obsidian-wiki/config.$1" ]] && { echo "$HOME/.obsidian-wiki/config.$1"; return; }
    echo ""; return   # named vault missing → caller reports + lists, no fallback
  fi
  dir="$PWD"
  while [[ "$dir" != "$HOME" && "$dir" != "/" ]]; do
    [[ -f "$dir/.env" ]] && grep -q "OBSIDIAN_VAULT_PATH" "$dir/.env" && { echo "$dir/.env"; return; }
    dir="$(dirname "$dir")"
  done
  [[ -f "$HOME/.obsidian-wiki/config" ]] && { echo "$HOME/.obsidian-wiki/config"; return; }
  echo ""
}

Vault-scoped state

Skills that write runtime state (e.g. daily-update) must scope that state to the resolved vault, not to a global path. Use:

VAULT_ID=$(echo "$OBSIDIAN_VAULT_PATH" | md5sum 2>/dev/null || md5 -q - <<< "$OBSIDIAN_VAULT_PATH" | cut -c1-8)
STATE_DIR="$HOME/.obsidian-wiki/state/$VAULT_ID"

Standard "Before You Start" block

Every skill's setup section should read:

Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md. Honor an inline @name override first, then walk up from CWD for .env, fall back to ~/.obsidian-wiki/config, else prompt setup. This gives OBSIDIAN_VAULT_PATH and any tool-specific path overrides.

Environment Variables

The wiki is configured through environment variables (see .env.example). The only required variable is the vault path — everything else has sensible defaults.

• OBSIDIAN_VAULT_PATH — Where the wiki lives (required)
• OBSIDIAN_SOURCES_DIR — Where raw source documents are
• OBSIDIAN_CATEGORIES — Comma-separated list of categories
• WIKI_SKIP_PROJECTS — Comma-separated substrings; any project dir whose name contains one is excluded from history ingest (scan + delta + manifest). See the "Project Scoping" step in the history-ingest skills.
• CLAUDE_HISTORY_PATH — Where to find Claude conversation data
• CODEX_HISTORY_PATH — Where to find Codex session data
• HERMES_HOME — Where to find Hermes agent data
• OPENCLAW_HOME — Where to find OpenClaw data
• COPILOT_HISTORY_PATH — Where to find Copilot session data
• OBSIDIAN_LINK_FORMAT — Internal link syntax: wikilink (default) or markdown
• WIKI_TOKEN_WARN_THRESHOLD — Emit a warning in wiki-status when the full-wiki token estimate exceeds this value (default: 100000). Set to 0 to disable. See wiki-status for the token footprint report.
• WIKI_STAGED_WRITES — When true, all LLM-written pages go to _staging/<category>/ for human review before promotion. See wiki-setup and wiki-stage-commit for details.

No API keys are needed — the agent running these skills already has LLM access built in.

Modes of Operation

The wiki supports three ingest modes:

Use wiki-status to see the delta and get a recommendation. Use wiki-rebuild for archive/rebuild/restore operations.

Reference

For details on specific operations, see the companion skills:

• wiki-status — Audit what's ingested, compute delta, recommend append vs rebuild
• wiki-rebuild — Archive current wiki, rebuild from scratch, or restore from archive
• wiki-ingest — Distill source documents into wiki pages and raw text/chat/log data
• claude-history-ingest — Ingest Claude conversation history
• codex-history-ingest — Ingest Codex CLI session history
• wiki-query — Answer questions against the wiki
• wiki-lint — Audit and maintain wiki health
• wiki-setup — Initialize a new vault

Memory Bridge — Cross-Tool Knowledge Browser

You are helping the user browse and compare their Obsidian wiki knowledge filtered by which AI tool originally produced it. The wiki tracks source provenance in .manifest.json and page sources: frontmatter — this skill surfaces that metadata as a navigable view.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH.
2. Read $OBSIDIAN_VAULT_PATH/.manifest.json — this is the source-of-truth for what tool produced what.
3. Read $OBSIDIAN_VAULT_PATH/index.md for page titles and one-line descriptions.

Commands

Parse the user's invocation to determine mode:

Recognized tool names: claude, codex, hermes, openclaw, copilot, pi, manual (hand-written), ingest (wiki-ingest documents).

Step 1: Build the Source Map

Read .manifest.json. For each source entry, extract:

• source_type — maps to tool name:
  • claude_conversation, claude_memory, claude_audit_log, claude_desktop_session → claude
  • codex_rollout, codex_index, codex_history → codex
  • hermes_memory, hermes_session → hermes
  • openclaw_memory, openclaw_daily_note, openclaw_session, openclaw_dreams → openclaw
  • copilot_session, copilot_checkpoint, copilot_transcript, copilot_memory_artifact → copilot
  • pi_session → pi
  • document → ingest
  • anything else → manual
• pages_created and pages_updated — the wiki pages that came out of this source

Build a map:

tool_pages = {
  "claude": set(pages created/updated by claude sources),
  "codex":  set(pages created/updated by codex sources),
  ...
}

A page can appear in multiple tools' sets if multiple tools contributed to it.

Step 2: Execute the Mode

Browse Mode

Filter tool_pages[<tool>] and present as a grouped list:

## Knowledge from <tool> (<N> pages)

### By category
- concepts/ — N pages
- entities/ — N pages
- skills/   — N pages
...

### Pages
| Page | Category | Tags | Last updated |
|------|----------|------|--------------|
| [[page-name]] | concept | tag1, tag2 | 2026-04-10 |
...

Read frontmatter for the listed pages (grep for ^(title|category|tags|updated):) — do not read full page bodies unless the user asks.

Search Mode

Within the filtered page set, run:

grep -l "<topic>" <pages in tool set>

Then grep section headers (^##) around matches to give context without full reads. Present results as a ranked list with the matching excerpt.

Diff Mode

Compute:

• only_in_a = tool_pages[a] − tool_pages[b]
• only_in_b = tool_pages[b] − tool_pages[a]
• shared = tool_pages[a] ∩ tool_pages[b]

If no specific tools are given, compare all tools pairwise (limit to pairs with >0 overlap or unique pages to keep output concise).

Present:

## Memory Bridge Diff — <tool-a> vs <tool-b>

### Only in <tool-a> (<N> pages)
These concepts exist in your wiki from <tool-a> sessions but <tool-b> has never touched them.
<list with one-line descriptions from index.md>

### Only in <tool-b> (<N> pages)
<list>

### Shared (<N> pages)
Both tools have contributed to these pages.
<list — only show if ≤15; otherwise just the count>

### Notable gaps
<highlight the most interesting asymmetries — e.g. "codex has 12 pages on build tooling that claude has never seen">

Map Mode

Build a matrix showing every page and which tools have touched it. Cap at 50 rows; sort by number of contributing tools descending (most cross-tool pages first — these are the richest nodes).

| Page | claude | codex | hermes | copilot | pi |
|------|--------|-------|--------|---------|----|
| [[react-patterns]] | ✓ | ✓ | — | ✓ | — |
| [[rust-ownership]] | — | ✓ | — | — | ✓ |

Step 3: Spawn impl-validator (if available)

After generating output, if the impl-validator skill is available in the current environment, spawn it as a subagent:

impl-validator check:
  goal: "Browse/diff wiki knowledge by source tool and surface cross-tool blind spots"
  artifacts: [the output you just generated]
  checks:
    - Did you correctly parse source_type from .manifest.json?
    - Are page counts plausible (not 0 unless vault is empty)?
    - Is the diff symmetric (a−b and b−a are disjoint)?
    - Did you avoid reading full page bodies when not needed?

Apply any issues it surfaces before presenting output to the user.

Step 4: Log

Append to $OBSIDIAN_VAULT_PATH/log.md:

- [TIMESTAMP] MEMORY-BRIDGE mode=<browse|search|diff|map> tool=<tool> pages_shown=N

Output Conventions

• Always show page counts so the user can calibrate how much knowledge is in each tool's silo.
• Use [[wikilinks]] for page references (or standard Markdown links if OBSIDIAN_LINK_FORMAT=markdown is set).
• In diff mode, call out the most surprising asymmetry explicitly — that's the insight the user came for.
• If .manifest.json is empty or missing, say so clearly and suggest running /wiki-history-ingest first.

Tag Taxonomy — Controlled Vocabulary for Wiki Tags

You are enforcing consistent tagging across the wiki by normalizing tags to a controlled vocabulary.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH
2. Read $OBSIDIAN_VAULT_PATH/_meta/taxonomy.md — this is the canonical tag list
3. Read index.md to understand the wiki's scope

The Taxonomy File

The canonical tag vocabulary lives at $OBSIDIAN_VAULT_PATH/_meta/taxonomy.md. It defines:

• Canonical tags — the tags that should be used
• Aliases — common alternatives that should be mapped to the canonical form
• Rules — max 5 tags per page, lowercase/hyphenated, prefer broad over narrow
• Migration guide — specific renames for known inconsistencies

Always read this file before tagging. It's the source of truth.

Reserved System Tags

visibility/ is a reserved tag group with special rules. These tags are not domain or type tags and are managed separately from the taxonomy vocabulary:

Rules for visibility/ tags:

• They do not count toward the 5-tag limit
• Only one visibility/ tag per page
• Omit entirely when content is clearly public — no tag needed
• Never add visibility/internal just because content is technical; use it only for genuinely team-restricted knowledge
• When running a tag audit, report visibility/ tag usage separately — do not flag them as unknown or non-canonical

When normalizing tags, leave visibility/ tags untouched — they are not subject to alias mapping.

Mode 1: Tag Audit

When the user wants to see the current state of tags:

Step 1: Scan all pages

Glob: $VAULT_PATH/**/*.md (excluding _archives/, .obsidian/, _meta/)
Extract: tags field from YAML frontmatter

Step 2: Build a tag frequency table

For each tag found, count how many pages use it. Flag:

• Unknown tags — not in the taxonomy's canonical list
• Alias tags — using an alias instead of the canonical form (e.g., nextjs instead of react)
• Over-tagged pages — pages with more than 5 tags
• Untagged pages — pages with no tags or empty tags field

Step 3: Report

## Tag Audit Report

### Summary

- Total unique tags: 47
- Canonical tags used: 32
- Non-canonical tags found: 15
- Pages over tag limit (5): 3
- Untagged pages: 2

### Non-Canonical Tags Found

| Current Tag | → Canonical | Pages Affected |
| ----------- | ----------- | -------------- |
| `nextjs`    | `react`     | 4              |
| `next-js`   | `react`     | 2              |
| `robotics`  | `ml`        | 1              |
| `windows98` | `retro`     | 3              |

### Unknown Tags (not in taxonomy)

| Tag          | Pages | Recommendation                   |
| ------------ | ----- | -------------------------------- |
| `flutter`    | 1     | Add to taxonomy under Frameworks |
| `kubernetes` | 2     | Add to taxonomy under DevOps     |

### Over-Tagged Pages

| Page                   | Tag Count | Tags                 |
| ---------------------- | --------- | -------------------- |
| `entities/jane-doe.md` | 8         | ai, ml, founder, ... |

Mode 2: Tag Normalization

When the user wants to fix the tags:

Step 1: Run audit (above)

Step 2: Apply fixes

For each page with non-canonical tags:

1. Read the page
2. Replace alias tags with their canonical form from the taxonomy
3. If page has > 5 tags, suggest which to drop (keep the most specific/relevant ones)
4. Write the updated frontmatter

Example:

# Before
tags: [nextjs, ai, ml-engineer, windows98, creative-coding, game, 8-bit, portfolio]

# After
tags: [react, ai, ml, retro, generative-art]

Step 3: Handle unknowns

For tags that aren't in the taxonomy and aren't aliases:

• If the tag is used on 2+ pages, suggest adding it to the taxonomy
• If the tag is used on 1 page, suggest replacing it with the closest canonical tag
• Ask the user before making changes to unknown tags

Step 4: Update taxonomy

If new canonical tags were agreed upon, append them to _meta/taxonomy.md in the correct section.

Mode 3: Tagging a New Page

When you're creating a wiki page and need to choose tags:

1. Read _meta/taxonomy.md
2. Select up to 5 tags that best describe the page:
   • 1-2 domain tags (what subject area)
   • 1 type tag (what kind of thing)
   • 0-1 project tags (if project-specific)
   • 0-1 additional descriptive tags
3. Use only canonical tags — never aliases
4. If no existing tag fits, check if it's worth adding to the taxonomy

Mode 4: Adding a New Tag

When the user wants to add a tag to the vocabulary:

1. Check if an existing tag already covers the concept (suggest it if so)
2. If genuinely new, determine which section it belongs in (Domain, Type, Project)
3. Add it to _meta/taxonomy.md with:
   • The canonical tag name
   • What it's used for
   • Any aliases to redirect

After Any Tag Operation

Append to log.md:

- [TIMESTAMP] TAG_AUDIT tags_normalized=N unknown_tags=M pages_modified=P

Or for normalization:

- [TIMESTAMP] TAG_NORMALIZE tags_renamed=N pages_modified=M new_tags_added=P

hot.md — Read $OBSIDIAN_VAULT_PATH/hot.md (create from the template in wiki-ingest if missing). Update Recent Activity with a one-line summary — e.g. "Tag audit: normalized 14 tags across 28 pages; 2 new canonical tags added." Keep the last 3 operations. Update updated timestamp.

QMD Refresh After Vault Writes

QMD is a search index, not the source of truth. If $QMD_WIKI_COLLECTION is empty or unset, skip this step. Run it only after this skill has written or rewritten vault markdown. If QMD refresh fails, do not roll back the vault changes; report the QMD status separately.

Use $QMD_CLI if set; otherwise use qmd.

${QMD_CLI:-qmd} update

If the output says vectors are needed or embeddings may be stale, run:

${QMD_CLI:-qmd} embed

Verify the collection with either:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

or, when a specific page path is known:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

Record one of:

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

Vault Skill Factory

You turn a cluster of mature, curated wiki pages into a portable Agent Skill: a SKILL.md plus a references/ folder, written to a review directory for the human to inspect and (only if they choose) install. This is the inverse of wiki-capture: capture turns a conversation into a page; the factory turns a body of pages into a reusable skill.

Hard guardrails (read first)

• Never write into .skills/ and never run setup.sh or create symlinks into any global skill directory (~/.claude/skills, ~/.codex/skills, …). Generated skills go to the review dir only. Installation is a separate, explicit human decision.
• Never auto-install. End by telling the user where the skill is and how to install it project-locally if they want — do not do it for them.
• Source pages are trusted vault content, but do not invent capabilities: the generated skill must reflect what the pages actually say.

Before You Start

1. Resolve config (Config Resolution Protocol in llm-wiki/SKILL.md): get OBSIDIAN_VAULT_PATH, OBSIDIAN_WIKI_REPO, OBSIDIAN_LINK_FORMAT, the QMD vars, and:
   • SKILL_FACTORY_OUTPUT_DIR — where generated skills land. Default: $OBSIDIAN_VAULT_PATH/_generated-skills (a vault-level, underscore-prefixed excluded dir — like _raw/_staging/_sources, NOT the skills/ knowledge category). This co-locates generated skills with the vault they were distilled from. Create it if missing. Note: _generated-skills/ holds runtime Agent-Skill bundles (name + description frontmatter), not wiki pages — never write them into skills/ (that category is for knowledge pages and is graph-/lint-/index-tracked).
   • SKILL_FACTORY_MATURITY — comma list of lifecycle: values that count as "mature". Default: reviewed,verified. Pages with tier: core also qualify.
2. Read index.md to understand what the vault holds.

Step 1: Choose the cluster

Decide which pages become the skill. The user may name a topic, tag, or project; otherwise propose candidates.

1. Seed from the user's intent (a topic, tag, project, or a named page).
2. Expand the cluster:
   • If QMD is configured (QMD_WIKI_COLLECTION), run qmd query "<topic>" -c "$QMD_WIKI_COLLECTION" --files (or vsearch) to gather semantically related pages — this is the intended way to find the full cluster, not just exact-tag matches.
   • Otherwise Grep/Glob by tag and wikilink-neighbourhood (pages linked from the seed pages).
3. Filter by maturity: keep pages whose lifecycle: is in SKILL_FACTORY_MATURITY or whose tier: is core. Drop draft pages unless the user explicitly includes them.
4. Confirm the cluster with the user (list page names + count) before generating. If fewer than ~3 mature pages match, say so — a skill from one thin page isn't worth it; offer to proceed anyway or widen the net.

Step 2: Design the skill

From the cluster, decide:

• name — kebab-case, derived from the cluster's subject (e.g. french-theory-expert, peptide-protocols). Must not collide with an existing skill in .skills/.
• description — the trigger. Write it "pushy" (per skill-creator): state when to use it (all the phrasings a user might say) and what it does. This field is what makes the skill fire.
• Reasoning approach — how an agent should use this knowledge: the questions it answers, the method it applies, the caveats it respects. Distil this from the pages' synthesis, not a copy-paste.
• Depth material — which page bodies become references/ files.

Step 3: Write the skill to the review dir

Create $SKILL_FACTORY_OUTPUT_DIR/<name>/ with:

<name>/
├── SKILL.md            # frontmatter (name + pushy description) + reasoning approach + key knowledge
├── references/         # depth material distilled from the cluster
│   ├── <topic>.md      # one per sub-theme; declarative knowledge, not chat
│   └── sources.md      # provenance: which vault pages this was built from (+ their sources)
└── SKILL_FACTORY.md    # provenance manifest (see below) — NOT part of the installed skill

SKILL.md body should be lean (the trigger logic + a compact reasoning guide), pushing depth into references/. Follow the structure of existing skills in this repo. Preserve ^[inferred] / ^[ambiguous] markers when carrying over uncertain claims — a generated skill must not launder synthesis into fact.

references/sources.md lists every vault page used (by [[wikilink]]) and their upstream sources: — so the skill stays auditable back to the vault and original sources.

SKILL_FACTORY.md (factory metadata, kept out of the installable skill) records: generation date, the cluster pages + their lifecycle/tier, the maturity filter used, and the vault commit/hash if available. This lets a regenerate-on-update workflow diff later.

Optional, if the user asks: append/update a marketplace.json entry in the output dir (the OpenKB one-line-install convention) — still not an install, just a manifest.

Step 4: Optionally lean on skill-creator

skill-creator ships reusable scripts ($OBSIDIAN_WIKI_REPO/.skills/skill-creator/scripts/):

• improve_description.py — tighten the generated description for better triggering.
• package_skill.py — bundle the skill dir into a distributable archive.
• quick_validate.py — sanity-check the skill's structure.

Use them when the user wants a polished/validated artifact; don't reinvent them.

Step 5: Report — and stop

Tell the user:

• the path: $SKILL_FACTORY_OUTPUT_DIR/<name>/
• the cluster it was built from (page count + names)
• the trigger description
• How to install if they want it (their decision, project-local only):

  ln -s ../../.skills/<name> <repo>/.claude/skills/<name>   # after copying <name>/ into .skills/, sans SKILL_FACTORY.md
  

  Note explicitly: review first; do not run setup.sh (it fans skills into global dirs); never global-install without explicit agreement.

Do not install it yourself. Do not write to .skills/. Done.

Quality checklist

• Output went to $SKILL_FACTORY_OUTPUT_DIR, never .skills/ or a global dir
• Cluster confirmed with the user; only mature pages (per SKILL_FACTORY_MATURITY / tier: core)
• description is pushy and accurate (when + what)
• SKILL.md body is lean; depth lives in references/
• ^[inferred]/^[ambiguous] markers preserved; no synthesis laundered into fact
• references/sources.md traces back to vault pages + their sources
• SKILL_FACTORY.md provenance manifest present (excluded from the installable skill)
• Report names the path and the manual, project-local-only install step; nothing auto-installed

Wiki Agent — Targeted Cross-Agent History Search + Ingest

You are doing a query-driven targeted ingest from one specific AI agent's raw conversation history. The user is typically working in a different agent right now and wants to pull in context from another agent's past sessions.

This is not bulk ingest. You find sessions about a specific topic, extract the relevant blobs, distill them into the wiki, and return a synthesized answer the user can act on immediately.

Command Routing

Parse the invocation to determine the target agent and optional query:

If no query is given, default to recent sessions mode: ingest the last 5 unprocessed sessions from that agent and return a summary of what was found. This is equivalent to a focused wiki-history-ingest for that agent only.

Before You Start

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → ~/.obsidian-wiki/config → prompt setup). This gives OBSIDIAN_VAULT_PATH.
2. Read $OBSIDIAN_VAULT_PATH/.manifest.json → know what's already ingested.
3. Read $OBSIDIAN_VAULT_PATH/hot.md if it exists → warm context on recent wiki activity.

Step 1: Locate the Agent's History Root

If the history root doesn't exist, stop and tell the user: "No <agent> history found at <path>. Have you run <agent> on this machine? You can set a custom path with <CONFIG_VAR> in .env."

Step 2: Build Session Inventory

Use the cheapest index source for each agent — don't open session files until you know which ones are relevant.

Claude

Primary index:   ~/.claude/projects/  (directories = projects, files = sessions)
Session files:   ~/.claude/projects/*/*.jsonl
Desktop index:   find ~/Library/Application Support/Claude/local-agent-mode-sessions -name "local_*.json"
Signal fields:   sessionId, cwd, startedAt, title (in local_*.json)

Build a list of sessions: {path, project_dir, modified_at, already_ingested}.

Codex

Primary index:   ~/.codex/session_index.jsonl
Session files:   ~/.codex/sessions/**/rollout-*.jsonl
Signal fields:   thread_id, name/title, updated_at (in session_index.jsonl)

Read session_index.jsonl as the inventory. Each line: {thread_id, name, updated_at}. Map thread IDs to rollout files by matching directory names.

Hermes

Primary index:   ~/.hermes/memories/*.md  (fast to scan)
Session files:   ~/.hermes/sessions/**/*.jsonl
Signal fields:   file names, memory titles, first 3 lines of each memory

Scan memory filenames first (they're often titled by topic). Fall back to session listing.

OpenClaw

Primary index:   ~/.openclaw/workspace/memory/MEMORY.md  (structured long-term memory)
Daily notes:     ~/.openclaw/workspace/memory/YYYY-MM-DD.md
Session index:   ~/.openclaw/agents/*/sessions/sessions.json
Session files:   ~/.openclaw/agents/*/sessions/*.jsonl

Read MEMORY.md sections first — it's the pre-compiled summary of everything. Daily notes give recency signal.

Copilot

Primary index:   session filenames / directory listing
Session files:   varies by client (VS Code: ~/.copilot/sessions/*.jsonl or similar)
Signal fields:   session timestamps, file names

Pi

Primary index:   ~/.pi/agent/sessions/--<cwd>--/ directories
Session files:   ~/.pi/agent/sessions/--<cwd>--/<timestamp>_<uuid>.jsonl
Signal fields:   cwd (decoded from dir name), session_info.name, timestamp in filename

Scan session directories first. Decode --<cwd>-- to get the working directory. Read the first line (session header) and any session_info entries for the session name. No separate index file — the filesystem is the index.

Step 3: Score Sessions Against the Query

If a query was given, score each session in the inventory without opening full session files:

1. Name/title match — does the session name or thread title contain the query terms? Score: +3
2. CWD/project match — does the working directory suggest the right project? Score: +2
3. Recency — sessions from the last 90 days score higher than older ones. Score: +1 per 30-day recency bracket (max +3)
4. Already ingested — if this session was previously ingested and the wiki page already covers the query (check hot.md + index.md), flag as "covered" but still show in results

Select the top 3–5 sessions by score. If no query was given, select the 5 most recent unprocessed sessions.

Step 4: Extract the Relevant Blob

Open each selected session file and extract only the content relevant to the query. Do not read the full session if it's large — use targeted extraction.

Per-Agent Extraction Strategy

Claude (JSONL conversation):

• Each line: {role, content, timestamp, ...}
• Search with: grep -i "<query terms>" <session.jsonl> to find the relevant lines
• Extract: the surrounding conversation window (10 lines before + 20 lines after each hit)
• Special signal: tool calls (Read/Write/Bash/Edit) reveal what was actually done — extract these even without keyword matches if they're in the relevant window

Codex (rollout JSONL):

• Each line: {type: "session_meta|turn_context|event_msg|response_item", ...}
• Filter to type: "event_msg" (user turns) and type: "response_item" (model output)
• Search with: grep -i "<query terms>" <rollout.jsonl>
• Extract: matching turns + their parent context (the turn_context preceding the match)
• Skip: session_meta events (operational metadata, not knowledge)

Hermes (memory files + session JSONL):

• For memory files: read the full file (they're short — typically <500 words each)
• For session JSONL: grep -i "<query terms>" + surrounding window
• Memory files with title matches → read fully; others → grep only

OpenClaw (MEMORY.md + daily notes + session JSONL):

• MEMORY.md: grep for section headers containing query terms → extract that section
• Daily notes: grep most recent 30 days for query terms → extract matching paragraphs
• Session JSONL: same grep-window approach as Claude
• Prefer MEMORY.md/daily notes over session JSONL (they're pre-synthesized)

Copilot (session JSONL):

• Same grep-window approach as Claude
• Look for checkpoint files if available (pre-summarized)

Pi (structured JSONL with tree layout):

• Each line is a tree entry: {type, id, parentId, timestamp, message?, ...}
• Build the active branch: map entries by id, find leaf (last entry with no children), walk parentId to root
• Search with: grep -i "<query terms>" <session.jsonl> to find matching entries
• Extract: the matching entries + their ancestors on the active branch (follow parent chain)
• Special signal: toolCall blocks inside assistant messages reveal what was actually done — extract these even without keyword matches if they're in the relevant window
• Prefer compaction and branch_summary entries when available — they're pre-synthesized summaries
• Skip thinking content blocks (noise) and model_change / thinking_level_change entries

Step 5: Distill Blobs into Wiki Pages

For each extracted blob, determine where it belongs in the wiki:

1. Check if a wiki page already covers this — grep index.md and page frontmatter for the topic. If yes, update the existing page rather than creating a new one.
2. Determine category using standard rules (from llm-wiki/SKILL.md):
   • Technique / how-to → skills/
   • Abstract concept / pattern → concepts/
   • Tool / library / person → entities/
   • Cross-cutting insight → synthesis/
3. Write or update the page with required frontmatter:

   ---
   title: <topic>
   category: skill|concept|entity|synthesis
   tags: [tag1, tag2]
   sources: [<agent>://<path/to/session>]
   created: <date>
   updated: <date>
   confidence: high|medium|low
   lifecycle: stable|draft
   ---
   

   Set sources with the agent prefix so memory-bridge can find it later.
4. Add cross-links to related wiki pages found in index.md.