📦 Obsidian Wiki — 技能工具

Implements Karpathy's LLM Wiki pattern inside an Obsidian vault. The agent is the compiler; Obsidian is the IDE; the wiki is the codebase.

Vault Resolution

Resolve the vault path at runtime. Store it in $VAULT for all operations.

Preferred methods (in order):

• If the user specifies a vault path, use it directly
• Read the Obsidian config file to find the open vault:

python3 -c "
import json, pathlib, os
# Obsidian stores vault config in a platform-dependent location
for p in [
    'Library/Application Support/obsidian/obsidian.json',
    '.config/obsidian/obsidian.json',
    '.var/app/md.obsidian.Obsidian/config/obsidian/obsidian.json',
]:
    f = pathlib.Path.home() / p
    if f.exists():
        for v in json.loads(f.read_text()).get('vaults',{}).values():
            if v.get('open'): print(v['path']); break
        break
"

• Use obsidian-cli print-default --path-only if available
• Before any write, print the resolved $VAULT path. If it was inferred via Obsidian config or obsidian-cli, get user confirmation before continuing.

The skill and scripts make no assumptions about the vault location. All paths are relative to $VAULT. Scripts require Bash and python3; they use BSD-compatible grep/sed/awk and are tested on macOS and Linux.

Vault Layout

/
├── raw/                    # Immutable source documents
│   ├── articles/           # Web clips, blog posts
│   ├── papers/             # arXiv, IEEE, ACM papers
│   ├── projects/           # Project notes, meeting transcripts
│   ├── books/              # Book chapters, excerpts
│   └── assets/             # Images, diagrams (downloaded locally)
├── wiki/                   # LLM-compiled pages (agent-owned)
│   ├── entities/           # People, systems, projects, orgs
│   ├── concepts/           # Ideas, patterns, technologies, methods
│   ├── syntheses/          # Cross-cutting summaries, comparisons
│   ├── sources/            # One summary page per ingested source
│   ├── reports/            # Agent-generated dashboards (agent creates during maintain workflow)
│   ├── index.md            # Auto-generated TOC
│   └── log.md              # Append-only chronological record
├── _meta/
│   ├── schema.md           # Wiki conventions (co-evolves with user)
│   └── taxonomy.md         # Canonical tag vocabulary
├── .wiki-meta/             # Machine state (not for humans)
│   └── manifest.json       # Delta tracking: ingested files + SHA-256 hashes
├── AGENTS.md               # Agent instructions for this vault
└── .obsidian/              # Obsidian config (don't touch)

Ownership rules

• raw/ — immutable. The agent reads but never modifies.
• wiki/ — agent-owned. The agent creates, updates, and maintains all pages.
• _meta/ — co-owned. The agent proposes changes; the user approves.
• .wiki-meta/ — machine-only. Delta tracking, caches.
• Everything else in the vault is untouched.

Page Format

---
title: 
type: entity | concept | synthesis | source | report
tags: [from taxonomy.md]
sources: [raw/path/to/source.md]
created: YYYY-MM-DD
updated: YYYY-MM-DD
confidence: high | medium | low       # optional
status: active | review | stale | archived  # optional
# 
Content with [[wikilinks]] to other wiki pages.
Open Questions
Unresolved questions about this topic
Sources
raw/path/to/source.md — what this source contributed

Provenance markers

Use Obsidian comment syntax %%...%% (invisible in reading view, visible in edit mode):

• %%from: raw/path/to/source.md%% — claim extracted from this source
• %%inferred%% — LLM synthesis across multiple sources
• %%ambiguous: explanation%% — sources disagree

Page-level provenance goes in frontmatter sources: field. Inline provenance is optional, for granular paragraph-level attribution.

Do NOT use ^[...] — that is Obsidian's inline footnote syntax.

Wikilink rules

• Obsidian resolves wikilinks by FILENAME only — not by title or aliases.
• Always write links as [[filename|Display Title]]. Example: [[convolutional-neural-network|Convolutional Neural Network]]
• In markdown tables: the | in wikilinks conflicts with table column separators.

Prefer bullet lists over tables when cells contain wikilinks. If a table is necessary, use \| inside the wikilink: [[filename\|Title]]. The lint and fix scripts handle this escaping transparently.

• Reference raw sources as plain paths in frontmatter sources: and in ## Sources sections.
• For sections: [[filename#Section|Display]]
• Run scripts/fix-wikilinks.py "$VAULT" after creating pages to auto-rewrite any [[Title]] links to [[filename|Title]] format.

Workflows

1. Setup

Initialize the vault structure. Create dirs, then:

• Copy references/schema-template.md → _meta/schema.md
• Copy references/taxonomy-template.md → _meta/taxonomy.md
• Copy references/agents-template.md → AGENTS.md
• Customize AGENTS.md for the vault's domain
• Propose changes to _meta/schema.md and _meta/taxonomy.md; edit them only after user approval
• Create wiki/index.md, wiki/log.md

Source of truth: once copied, _meta/ and AGENTS.md are the live instances. references/ are generic starter templates — they do not stay in sync.

2. Ingest

• Run scripts/wiki-manifest.sh "$VAULT" diff to see pending sources
• For each pending file:

- Read the source, identify entities, concepts, claims, relationships - Create a source summary in wiki/sources/ - Create or update entity/concept pages with [[wikilinks]] - Track provenance in frontmatter sources: field

• Mark ingested: scripts/wiki-manifest.sh "$VAULT" mark
• Regenerate index: scripts/wiki-index.sh "$VAULT"
• Append to wiki/log.md:

   ## [YYYY-MM-DD] ingest | 
   - Source: raw/
   - Pages created: 
   - Pages updated: 
   

Source types:

• .md / .txt — read directly with read tool
• .pdf — use pdf tool to extract content (copy to workspace first if the file is outside it, then clean up)
• .epub / .html — convert to text or extract content before ingesting
• URL — use web_fetch to save as .md in raw/articles/, then ingest the .md
• Images in raw/assets/ — referenced by pages, not ingested independently (the manifest tracks only ingestable document sources)

3. Query

• Read wiki/index.md to find relevant pages
• Read relevant pages, synthesize an answer with [[wikilink]] citations
• Offer to save valuable answers as new pages in wiki/syntheses/

4. Lint

Run scripts/wiki-lint.sh "$VAULT" for automated checks (frontmatter, broken wikilinks, orphans, stale pages, tag drift). Then manually review for:

• Contradictions between pages (requires reading, not scriptable)
• Missing pages: concepts mentioned in text but lacking their own page
• Weak cross-references that should be strengthened

5. Maintain

Periodic (heartbeat or manual):

• Run lint
• Scan for unlinked mentions of entity/concept names → add [[wikilinks]]
• If new tags emerged, propose an update to _meta/taxonomy.md; edit it only after user approval
• Populate wiki/reports/ with dashboards (open questions, contradictions, stale)
• Review stale pages, flag for update or archival

6. Navigate

Use the obsidian skill (if available) for CLI operations (search, open, move/rename with wikilink refactoring). For bulk reads/writes, use read/write tools directly.

Scripts

Bundled shell scripts require Bash (BSD-compatible grep/sed/awk). wiki-index.sh, wiki-lint.sh, wiki-manifest.sh, and fix-wikilinks.py require python3. extract-book-digests.sh additionally requires pdftotext. wiki-manifest.sh uses shasum or sha256sum when available and falls back to Python hashlib otherwise. Resolve to the directory containing this SKILL.md.

scripts/wiki-index.sh "$VAULT"

Regenerate wiki/index.md from frontmatter of all wiki pages.

scripts/wiki-lint.sh "$VAULT"

Structural health checks: missing frontmatter, broken wikilinks, orphan pages, stale content, tag drift. Outputs a summary with per-category counts.

scripts/wiki-manifest.sh "$VAULT"

Delta tracking via SHA-256 hashes in .wiki-meta/manifest.json.

wiki-manifest.sh "$VAULT" status        # raw vs ingested vs pending counts
wiki-manifest.sh "$VAULT" diff          # list files needing ingest
wiki-manifest.sh "$VAULT" mark    # mark a file as ingested

scripts/fix-wikilinks.py "$VAULT" [--dry-run]

Rewrite [[Title]] links to [[filename|Title]] format for Obsidian resolution. Run after bulk page creation. Use --dry-run to preview without writing.

scripts/extract-book-digests.sh

Extract first 12 pages of each PDF as text via pdftotext. Used for cross-validating wiki source pages against actual book content. Writes .txt outputs to ; prefer a directory under $VAULT/.wiki-meta/ unless the user explicitly asks for another location.

Tips

• Ingest one source at a time for best quality. Stay involved.
• Good answers → wiki pages. Don't let syntheses disappear into chat history.
• Graph view in Obsidian shows wiki shape: hubs, orphans, clusters.
• Dataview plugin queries frontmatter if installed.
• Git the vault for version history (recommended).
• Web Clipper browser extension gets articles into raw/ fastest.