Wiki

Wiki

This skill formalizes a notebook into a generated wiki workspace for easier indexing, organization, and retrieval.

What This Skill Owns

• Source notes stay in the notebook.
• Generated wiki artifacts live in a separate wiki root.
• The approved category tree lives at the top of index.md and is the classification reference.
• User preferences live in the RULES.md file to guide or override categorization decisions.
• Category, subcategory, and topic layers each get a generated markdown synthesis page.
• Generated category pages should carry lightweight frontmatter metadata so they behave like real synthesis notes in Obsidian and Dataview.
• The human-facing homepage belongs at HOME.md in the notebook root, not inside _WIKI/.
• Search combines obsidian-cli search-content when available, tag-aware note matching, and generated index/category search.
• log.md is the persistent record of adds, removals, and lint runs.
• Layer labels are written deterministically as layer1: ..., layer2: ..., layer3: ..., and deeper when needed, so prompts and search can target a specific depth.

Retrieval-First Principles

Use these principles when indexing or searching:

• Taxonomy should optimize for how a user will try to find a note later, not for academic purity alone.
• Prefer consolidating semantically overlapping branches when they lead to the same retrieval behavior.
• For dense concept families like frameworks, optimizers, or evaluation loops, keep sibling notes clustered unless there is a strong browsing reason to split them.
• Search should infer nearby concepts, aliases, tags, and hierarchy cues instead of depending on the exact phrase the user typed.
• Good answers should return note path, hierarchy, and a short evidence snippet, not just a title match.

Dispatch

Based on user intent, choose one of the following agent to dispatch the workflow.

1. agents/setup.md Use when the task is to establish the wiki for the first time by proposing an initial category tree.

2. agents/add.md Use for targeted note ingestion or when the user wants to add a few notes into the wiki. The agent will also maintain existing concept pages by integrating new information and noting contradictions.

3. agents/index.md Use for notebook-wide or folder-wide indexing, incremental refreshes, and rebuilds.

4. agents/search.md Use when the user wants answers or browsing help from the generated wiki.

5. agents/synthesize.md Use when the user wants a synthesized presentation of a topic assembled from matching notes. The agent can save valuable syntheses back into the user's notebook as new source notes to compound knowledge over time.

6. agents/homepage.md Use when the user wants to create or refresh the human-facing HOME.md, especially after indexing, synthesis rollups, or lint remediation.

7. agents/lint.md Use when the user wants validation, cleanup guidance, or integrity checks.

Config Contract

The backend resolves config in this order:

1. --config <path>
2. --root <notebook-root> or --path <notebook-root>
3. <current-working-directory>/_WIKI/config.json
4. built-in defaults using --root/--path or the current working directory as the notebook root

When running via uv --directory <wiki skill path>, always pass --root <notebook-root> or --config <notebook-root>/_WIKI/config.json. uv --directory changes the process working directory to the skill package, so cwd auto-discovery will otherwise look for the wrong _WIKI/config.json.

Use templates/config.json.example as the starting template.

Supported config fields:

{
  "notebook_root": "/absolute/path/to/notebook",
  "include_roots": [".", "Projects"],
  "exclude_globs": ["_WIKI/**", ".obsidian/**", "Templates/**"],
  "generated_root": "/absolute/path/to/notebook/_WIKI",
  "search": {
    "lexical_limit": 8
  }
}

include_roots are resolved relative to notebook_root unless absolute.

Model choice is not part of the backend config. Subagents should inherit the active model from the invoking skill/session.

Hierarchy Shape

The generated wiki should default to three hierarchy layers before note leaves, but may add deeper layers when a branch gets crowded or a concept is clearly dense enough to deserve a finer split.

Rule of thumb:

• Keep each level to roughly 5-15 children.
• Prefer broad, durable buckets over narrow one-off branches.
• Prefer real topics over generic buckets like Research, Papers, General, or Misc.
• Do not shoehorn notes into an existing branch when they point to a clearer topical subtree.
• Treat fallback branches as explicit review queues, not as real long-term categories.
• Expand the tree only when a concept clearly does not fit an existing branch.
• If a branch grows past roughly 15 direct children, or multiple notes form a clear dense cluster, add another layer instead of leaving an overloaded bucket.
• Consolidate overlapping systems buckets when they reflect the same browsing intent.
• Prefix each category row with its depth marker so the tree stays machine- and prompt-friendly.

Small example:

- layer1: [Computer Science](Computer Science)
  - layer2: [Artificial Intelligence](Artificial Intelligence)
    - layer3: [AI Agents](AI Agents)
      - layer4: [Optimization](Optimization)
        - Note 1 on DSPy
        - Note 2 on GEPA

Operating Rules

• Always run uv commands from the wiki skill directory, or use --directory <wiki skill path> to ensure dependencies are loaded correctly. When using --directory, also pass wiki --root <notebook-root> so the backend resolves the target notebook instead of the skill package directory.
• Let subagents interpret notes and queries.
• Let src/wikicli own deterministic operations like file IO, category-page regeneration, log updates, indexing, delegated search, and lint checks.
• Keep the approved category tree at the top of index.md as the classification reference for add and first-time index.
• Keep index.md focused on the category tree itself. Do not regenerate a second browse-by-category section below it.
• Keep HOME.md concise and human-facing. Prefer prose plus light emoji, with tables mainly for New Syntheses and Recent Notes.
• HOME.md is agent-owned. Only the homepage skill/agent workflow should write HOME.md; the deterministic Python backend must never write user-facing synthesis notes directly.
• When rendering the homepage tree, derive it from the backend wiki tree --format json command rather than hand-writing or improvising a parallel structure.
• New Syntheses should prefer a Dataview table built from synthesis-page metadata, especially category, summary, and modified.
• Generated category pages should include stable metadata fields like category, created, modified, summary, optional parent, wiki_role, wiki_kind, wiki_depth, wiki_note_count, wiki_child_count, and wiki_status so downstream homepage queries can treat them as synthesis documents.
• The summary field is agent-maintained. The Python backend preserves it but does not generate semantic summary text. Agents should keep it as a short human-facing highlight of the category itself, usually one or two sentences, not a list of note titles.
• Synthesis writing belongs to the skill and its agents, not to the deterministic Python backend. Let wiki.py preserve existing synthesis text and update deterministic structures like metadata, subcategory lists, references, and machine-facing indexes.
• The backend may emit deterministic tree, lint, list, search, and index outputs, but agents should read those outputs and synthesize the final human-facing homepage from them plus the relevant notes/category pages.
• Lint and synthesis workflows are not fully complete until they refresh HOME.md whenever their changes affect navigation, summaries, topic framing, or the user's front-door view of the notebook.
• When a category synthesis needs updating, integrate the new ideas organically into the existing ## Synthesis prose. Do not replace the whole synthesis with a fresh rewrite unless the user explicitly asks for a full resynthesis.
• Prefer index for broad refreshes and add for small targeted updates.
• lint evaluates source synchronization (missing notes, modified notes, unindexed notes) and should also flag empty leaf categories as taxonomy cleanup candidates. Agents should enforce category hygiene when calling add.
• index detects missing source notes, reports modified notes via source mtime, and rebuilds generated views.
• For notebook-wide indexing, classify new notes with subagents in parallel when feasible, but cap concurrency at 8 notes at a time.
• For broad or ambiguous note sets, have subagents propose better topical branches instead of forcing notes into a weak existing category.
• For taxonomy disputes, prefer the branch that would make future search queries easier to succeed.
• When a concept shows up across projects, papers, and inbox notes, cluster it consistently unless there is a strong reason to preserve source-folder distinctions.
• Use add only when a subagent has already normalized a single note into one packet:

# ensure dependencies come from the wiki skill and workspace state comes from the notebook root
uv run --directory <path to wiki skill> wiki --root <notebook-root> add --json '{"title":"Note title","summary":"One paragraph summary","category":"Layer 1 > Layer 2 > Layer 3","tags":["#tag-a"],"source":"relative/path/to/note.md"}'
uv run --directory <path to wiki skill> wiki --root <notebook-root> index

• Keep three layers as the default floor, not a hard ceiling. Add deeper layers when a branch becomes crowded or needs a finer conceptual split.
• Use the approved category tree from the top of index.md when classifying new notes. Add new subtrees only when the existing tree is clearly insufficient.
• When the notebook mixes AI Systems and Machine Learning Systems, prefer consolidating them under a shared Artificial Intelligence subtree when that matches how the user retrieves notes.
• Use the deterministic layer1:, layer2:, layer3:, and deeper layerN: labels when referring to branches in prompts, searches, or follow-up edits.
• Search responses should include hierarchy for each returned note whenever the backend can resolve it.
• Search responses should favor semantic matches with direct evidence over literal-but-weak text matches.
• Treat source notes as references; do not rewrite them in place.
• When changing this skill, always test it with a clean-slate subagent run rather than relying only on the current session context.