---
name: xzh-obsidian-llm-wiki
description: "Create, ingest, query, teach from, audit, and maintain Obsidian-style LLM Wiki knowledge bases. Use when building a persistent Markdown wiki from read-only source material; restructuring notes, books, papers, web clips, journals, or course material into topic, module, concept, entity, and source pages; maintaining wiki indexes and logs; writing Obsidian-compatible Markdown with frontmatter, wikilinks, embeds, callouts, Mermaid, KaTeX, Bases, or Canvas; using Obsidian audit plugins or a local web viewer for anchored human feedback; linting dead links, orphan pages, duplicate content, stale claims, missing sources, or unresolved feedback; and turning notes into teaching, Socratic review, debate, and judgment-building exercises."
---

# XZH Obsidian LLM Wiki

Build and maintain an Obsidian-compatible LLM Wiki: a persistent, cross-linked Markdown knowledge base compiled from source material and improved over time through ingest, query, teach, compile, lint, and audit operations.

This skill is intentionally general. Adapt to the user's existing vault layout, naming style, language, and schema instead of forcing a single directory structure.

## Capability Model

Combine four capability families:

- LLM Wiki pattern: compile raw sources into a durable wiki instead of re-retrieving raw documents on every question.
- LLM Wiki feedback stack: support persistent human feedback through `audit/`, the bundled Obsidian audit plugin, the bundled local web viewer, and shared audit schema utilities.
- Note rebuilder: restructure messy notes, book excerpts, exported notebooks, and learning materials into navigable, reviewable topic/module/concept/entity/source pages.
- Obsidian skills: write valid Obsidian-flavored Markdown and use wikilinks, embeds, callouts, properties, Bases, Canvas, Mermaid, KaTeX, and vault-aware conventions when relevant.

## First Inspect The Wiki

1. Find project instructions first: `CLAUDE.md`, `AGENTS.md`, `.codex/`, vault notes, or any user-provided schema.
2. Identify the source layer. Common names include `raw/`, `sources/`, `inbox/`, `clips/`, `notes/`, `documents/`, and `papers/`.
3. Identify the wiki layer. Common names include `wiki/`, `knowledge/`, `notes/`, or an Obsidian vault root.
4. Identify navigation and history files. Common patterns include `index.md`, `home.md`, `map-of-content.md`, `log.md`, `changelog.md`, or `log/YYYYMMDD.md`.
5. Preserve the existing structure unless the user asks to redesign it.

If there is no existing structure, create a small, explicit one:

```text
<wiki-root>/
  raw/
  wiki/
    index.md
    log.md
  audit/
    resolved/
```

For larger projects, use subfolders such as `wiki/topics/`, `wiki/modules/`, `wiki/concepts/`, `wiki/entities/`, and `wiki/sources/`.

## Core Rules

- Treat source files as read-only unless the user explicitly asks to modify or reorganize them.
- Compile knowledge into durable wiki pages; do not merely rewrite one source into one summary page by default.
- Prefer updating existing pages over creating duplicates.
- Use Obsidian wikilinks for internal relationships: `[[Page]]`, `[[Page#Heading]]`, `[[Page|Label]]`.
- Use standard Markdown links only for external URLs.
- Give each durable wiki page YAML frontmatter, a clear title, useful links, and a source section.
- Preserve uncertainty. Mark conflicts, stale claims, and competing interpretations explicitly.
- Keep navigation current. Any write operation should update the index/map and log/history when those files exist.
- Follow the vault's primary language and naming style. Do not mix filename languages unless the vault already does so.

## Operation Modes

Use the operation that matches the user's request.

- `init`: create a new wiki or normalize an empty vault.
- `ingest`: add source material and integrate it into the wiki.
- `query`: answer from the wiki and optionally save durable answers back into it.
- `compile`: reorganize existing notes into a clearer wiki structure.
- `lint`: check wiki health and fix safe issues.
- `audit`: process human comments, corrections, and review notes.
- `teach`: turn wiki material into guided learning, Socratic questioning, debate, judgment drills, and follow-up reading paths.

## Init

1. Ask for or infer the wiki root.
2. Create the minimum useful structure for the user's case.
3. Create an index or map-of-content page.
4. Create a log/history file if the user wants persistent maintenance.
5. Create or update a schema note describing scope, source policy, naming rules, page types, and workflows.
6. Log the initialization.

If the standard helper fits the project, run:

```bash
python scripts/scaffold.py <wiki-root> "<Topic Title>"
```

Only use the helper when its generated structure is appropriate. Otherwise create the files manually according to the existing vault conventions.

## Ingest

1. Read the target source in full when practical. For large batches, sample first and then process in coherent groups.
2. Read the index/map and relevant existing pages before writing.
3. Decide whether to update existing topic, module, concept, entity, or source pages.
4. Create new pages only when the content introduces a durable topic, reusable concept, important entity, or independently valuable source.
5. Add wikilinks in both directions where useful: topic to module, module to concept, concept to examples, entity to mentions.
6. Preserve source traceability with a `Sources` section or equivalent vault convention.
7. Update navigation and log the touched pages.

Do not assume every source deserves a standalone `source-*` page. Create source pages when provenance, citation, or source-level review matters.

When ingesting notes, books, or study material, also extract learning affordances:

- the question or real-world purpose the material helps answer
- claims worth testing
- concepts that need first-principles explanation
- examples, counterexamples, and boundary cases
- judgment prompts that force prioritization, tradeoff analysis, and taste
- links to adjacent pages that support deliberate practice

## Query

1. Start from the index/map, then read the relevant pages.
2. Follow one level of high-value wikilinks when needed.
3. Ground the answer in the wiki. If coverage is insufficient, say what is missing and suggest sources or pages to add.
4. Cite wiki pages with wikilinks in the response when useful.
5. If the answer is durable, such as a comparison, decision record, synthesis, or reusable explanation, save or propose saving it as a wiki page.
6. Update navigation and log if new content is written.

## Teach

Use teach when the user wants the wiki to support learning, reading, judgment, taste, or deeper understanding rather than only storage.

Apply these patterns selectively:

- Hunting method: read or retrieve with a real purpose. Identify the user's live question, scan multiple sources if available, stop on high-signal passages, and turn each "catch" into a note, question, or concept page. Do not reward completion for its own sake.
- Feynman method: ask the user to explain the idea plainly, then probe with Socratic questions until definitions, mechanisms, examples, and limits are clear enough for a child-level explanation.
- Debate method: stage a cross-disciplinary debate around a claim. Contrast viewpoints, incentives, failure modes, edge cases, and second-order effects. Use it to build non-consensus judgment rather than a single "correct" summary.

When writing teaching-oriented pages, include some of:

- `Why this matters`
- `Plain-language explanation`
- `Core claim`
- `Mechanism`
- `Example and counterexample`
- `Boundary conditions`
- `Socratic questions`
- `Debate prompts`
- `Judgment drills`
- `What would change my mind`
- `Sources`

Prefer compact prompts that the user can reuse during reading. Store durable learning exercises in the relevant concept or module page instead of leaving them only in chat.

## Compile

Use compile when the wiki needs structure work rather than simple ingest.

1. Identify overloaded pages, duplicates, weak navigation, missing backlinks, and inconsistent naming.
2. Split long pages into focused pages when they contain multiple reusable subtopics.
3. Merge near-duplicates when they express the same concept or entity.
4. Keep lightweight overview pages for navigation and focused detail pages for learning or reference.
5. Preserve provenance during moves, splits, and merges.
6. Update index/map and log structural changes.

Confirm before broad renames, mass moves, or changes that could break many links.

## Lint

Use lint for wiki health checks.

If the helper fits the structure, run:

```bash
python scripts/lint_wiki.py <wiki-root>
```

Otherwise inspect manually for:

- dead wikilinks
- orphan pages
- pages missing from the index/map
- duplicated topics or entities
- oversized pages that should be split
- missing source sections
- stale claims superseded by newer sources
- unresolved contradictions
- malformed frontmatter
- broken embeds or attachment links
- open audit items or unresolved review comments

Fix safe local issues directly. For structural changes such as merges, splits, and naming migrations, present a concise plan before editing.

## Audit

Use audit when the vault contains human comments, review files, correction notes, or an `audit/` directory. Feedback can be written manually, by the bundled Obsidian plugin, or by the bundled local web viewer.

If the standard helper fits, run:

```bash
python scripts/audit_review.py <wiki-root> --open
```

For each feedback item:

1. Read the feedback and target page.
2. Locate the relevant passage using anchors, quoted text, headings, or surrounding context.
3. Choose one outcome: accept, partially accept, reject, or defer.
4. Apply accepted changes to the wiki.
5. Record the resolution in the feedback file or log.
6. Move resolved audit files to `audit/resolved/` when that convention exists.

Never delete feedback history unless the user explicitly asks.

## Feedback Tools

This skill includes the feedback tooling from the LLM Wiki stack:

- `audit-shared/`: shared TypeScript schema, anchor, id, and serialization utilities.
- `plugins/obsidian-audit/`: Obsidian plugin for selecting text and filing anchored feedback into `audit/`.
- `web/`: local web viewer that renders Markdown, wikilinks, Mermaid, and KaTeX, and lets the user file feedback from a browser.

Read `references/audit-and-tooling.md` when asked to install, build, run, troubleshoot, or use these tools.

## Page Types

Use these page types as a flexible vocabulary, not a rigid taxonomy.

- Topic page: overview, scope, learning path, map of modules and concepts.
- Module page: detailed reusable explanation, process, mechanism, example set, or lesson.
- Concept page: definition, boundaries, related concepts, applications, and examples.
- Entity page: people, tools, organizations, projects, papers, datasets, places, or products.
- Source page: structured extraction from a single source or source bundle.
- Query/output page: durable answer promoted from a user question.
- Learning page or learning section: Socratic questions, debate prompts, exercises, judgment drills, and reading paths attached to a topic, module, or concept.

For detailed templates, read `references/wiki-patterns.md`.

## Obsidian Markdown

Use Obsidian-compatible Markdown:

- YAML frontmatter for metadata.
- Wikilinks for internal pages.
- Embeds for notes, images, audio, video, and PDFs.
- Callouts for warnings, summaries, questions, examples, and unresolved issues.
- Mermaid for diagrams.
- KaTeX for formulas.
- Obsidian Bases for structured views when the vault uses `.base` files.
- JSON Canvas for visual maps when a spatial overview is more useful than a note.

Read `references/obsidian-markdown.md` when syntax details matter.

## Scripts

Bundled scripts are optional helpers:

- `scripts/scaffold.py`: scaffold a standard LLM Wiki.
- `scripts/lint_wiki.py`: check links, orphan pages, index coverage, log shape, and audit shape.
- `scripts/audit_review.py`: group open and resolved audit files.

These scripts assume a fairly standard `raw/ + wiki/ + log/ + audit/` layout. If the user's vault differs, use the scripts as reference behavior rather than forcing a migration.

## References

- `references/wiki-patterns.md`: architecture, page types, naming, index, log, note rebuilding, and learning-oriented page patterns.
- `references/obsidian-markdown.md`: Obsidian frontmatter, wikilinks, embeds, callouts, Mermaid, and KaTeX.
- `references/audit-and-tooling.md`: audit workflow, plugin/web feedback tools, lint checks, Web Clipper, qmd, and related tooling.

## Done Criteria

A completed wiki operation should leave the vault in a navigable and traceable state:

- New knowledge is integrated into appropriate pages.
- Relevant existing pages are updated instead of duplicated.
- Pages include metadata, sources, and useful wikilinks.
- Navigation/index pages point to the changed content.
- Logs or history files record the operation when the vault uses them.
- Conflicts, uncertainty, and coverage gaps are visible rather than hidden.
- Learning-oriented requests produce reusable questions, exercises, debates, or judgment prompts, not just summaries.



