/agent-wiki

name: agent-wiki
description: "Incremental LLM-friendly wiki generator for Obsidian note vaults. Use when: (1) Building wiki from notes, (2) Ingesting notes to wiki, (3) Obsidian LLM wiki, (4) Incremental knowledge base management. Triggers: 'build wiki from notes', 'ingest notes to wiki', 'Obsidian LLM wiki', 'incremental knowledge base'."

agent-wiki

增量式 Obsidian 笔记仓库 Wiki 生成器，为 LLM 优化的知识库管理工具。

Prerequisites

pip install PyYAML

References (load on demand)

Detailed specs live under `references/` in this skill directory — read them only when the task needs them:

| File | Read when | |------|-----------| | `references/cli-matrix.md` | Need a subcommand's exact inputs or JSON output shape | | `references/topic-authoring.md` | Authoring/enriching topic pages (type taxonomy, per-type section templates, conflict convention, quality metric detail) | | `references/homepage.md` | Working on `wiki/index.md` (layout templates, managed cards, MCP → file write decision chain, optional CSS) | | `references/site-export.md` | Running/debugging `gen-site` (design system, page anatomy, determinism guarantees) | | `references/index-schema.md` | Consuming/producing index or frontmatter fields (full `.wiki-index.json` schema, Bases views, capture contract) |

Execution

The skill provides a Python CLI with the following subcommands:

# Initialize wiki structure
python scripts/agent_wiki_cli.py init --vault /path/to/vault

# Scan for changed sources
python scripts/agent_wiki_cli.py scan --vault /path/to/vault

# Plan a batched ingest: split pending sources into rounds (default 20/round)
python scripts/agent_wiki_cli.py plan --batch-size 20 --vault /path/to/vault

# Mark a round complete (verifies every doc in the batch was cache-put)
python scripts/agent_wiki_cli.py batch-done --batch 1 --vault /path/to/vault

# Get cache entry for a source
python scripts/agent_wiki_cli.py cache-get <relative-path> --vault /path/to/vault

# Record ingest result
python scripts/agent_wiki_cli.py cache-put <relative-path> --topics topic1.md,topic2.md --vault /path/to/vault

# Clean up deleted sources
python scripts/agent_wiki_cli.py cleanup --vault /path/to/vault

# Get wiki health status
python scripts/agent_wiki_cli.py status --vault /path/to/vault

# Rebuild the retrieval index (wiki/.wiki-index.json) without writing .base files
python scripts/agent_wiki_cli.py index --vault /path/to/vault

# Backfill source_type frontmatter to match each topic's sources[] file formats
python scripts/agent_wiki_cli.py normalize-source-type --vault /path/to/vault

# Generate Obsidian Bases (.base) views: wiki/index.base + <name>.base master table
python scripts/agent_wiki_cli.py gen-base --name sources --vault /path/to/vault

# Register an Agent-authored research report (wiki/queries/<name>.md) and tag kind: query
python scripts/agent_wiki_cli.py save-report <name> --vault /path/to/vault

# Generate per-topic JSON Canvas knowledge graphs under wiki/graphs/ (one topic or all)
python scripts/agent_wiki_cli.py gen-canvas --topic <name> --vault /path/to/vault
python scripts/agent_wiki_cli.py gen-canvas --all --vault /path/to/vault

# Build/refresh the wiki/index.md skeleton + its managed "工作区" card block
python scripts/agent_wiki_cli.py gen-home --vault /path/to/vault

# Render index.md without writing it, so an MCP-side conditional write can apply it
python scripts/agent_wiki_cli.py gen-home --emit-only --vault /path/to/vault

# Extract raw 作者 rows from each topic's source notes (read-only)
python scripts/agent_wiki_cli.py extract-authors --vault /path/to/vault

# Deduplicated first-author list per topic, for frontmatter backfill (read-only)
python scripts/agent_wiki_cli.py aggregate-authors --vault /path/to/vault

# Compute quality tier distribution and per-topic metrics (read-only)
python scripts/agent_wiki_cli.py quality --vault /path/to/vault

# Identify covered sources vs gaps (read-only)
python scripts/agent_wiki_cli.py coverage --vault /path/to/vault

# Inventory keywords across topics to derive subject categories (read-only)
python scripts/agent_wiki_cli.py keywords --vault /path/to/vault

# Get maintenance worklists: wanted (broken links) and stale topics (read-only)
python scripts/agent_wiki_cli.py worklist --vault /path/to/vault

# Generate static HTML site (optional, requires markdown package)
python scripts/agent_wiki_cli.py gen-site --vault /path/to/vault

**Vault Path Resolution**: Use `--vault PATH` or set environment variable `AGENT_WIKI_VAULT`. This is the agent-wiki **source scope**, which may be the registered Obsidian root or a child directory. Each scope owns its own `wiki/`; multiple scopes can coexist in one registered Obsidian vault. Paths in topic frontmatter/cache are relative to the selected scope.

CLI Command Matrix

All commands emit JSON on stdout and JSON errors on stderr with a non-zero exit code. Per-command inputs and output shapes: see `references/cli-matrix.md`.

Agent Workflow

Intent Routing

**Before any action, classify the user request into one of two modes. Default to Answer mode.**

| Trigger Signal | Mode | Action | Output | |---|---|---|---| | User is **asking / seeking explanation / requesting lookup** on a topic ("what is…", "compare…", "help me find…") — and **NOT** requesting wiki building | **Answer (default)** | Follow **Hybrid Retrieval Protocol** to answer → optionally `save-report` as a report | `wiki/queries/<name>.md` (kind: query), **does NOT create/modify topics** | | User **explicitly** requests "build / import / ingest / update / maintain wiki", or "create topics from these notes", or points to a vault/directory to be ingested | **Ingest/Maintain** | Follow **Standard / Batched Ingest** or **Bounded Enrichment** | `wiki/topics/<name>.md` (kind: topic) |

**Rules**:

• **Reports are the default output**. A regular question **never** triggers topic generation — unless the user explicitly requests wiki building/maintenance, or expl