--- name: obsidian-vault-builder description: Use when adding/editing/querying content in an existing Obsidian vault, configuring plugins, integrating Claude Code with Obsidian via Local REST API or CLI, automating ongoing capture/organization/retrieval, designing a personal knowledge management workflow, OR building academic study vaults (course prep, exam-ready, mock-exam content — the durable academic-study patterns from a deprecated companion skill have been folded into this one). metadata: version: 0.2.0 tags: - obsidian - knowledge-management - markdown - vaults - pkm - tools-for-thought --- # Obsidian Vault Builder (general PKM, multi-vault aware) Patterns for operating an Obsidian vault from Claude Code: capture pipelines, plugin selection, REST API integration, file-portability discipline, methodology choice. Multi-vault aware. For academic study vault construction (course prep, lecture notes, mock exams, exam-ready content): the durable patterns from the deprecated `obsidian-study-vault-builder` skill have been folded into this skill. See `references/academic-vault.md`. The companion skill itself was removed via PR #6 and re-validated 2026-05-15 (over-triggered on exam-prep prompts; structurally misaligned with the interactive-practice approach in `~/.claude/rules/exam-prep-protocol.md`). ## When to use - User asks to add/edit/query content in an Obsidian vault - User asks to install or configure Obsidian plugins - User wants to integrate Claude Code with Obsidian via Local REST API or CLI - User wants to automate ongoing capture/organization/retrieval - User wants to design a PKM workflow - User asks to build a course/exam/study vault (see `references/academic-vault.md`) ## Checkpoint-based vault build (greenfield, large generation tasks) When generating a vault from scratch or filling in many chapters/sections at once, never generate everything upfront. Use progressive validation: 1. First chapter / first section — then STOP 2. User review — approve format, structure, quality 3. Remaining chapters / sections — continue with validated pattern 4. Final QA pass — systematic verification per `references/qa-checklist.md` Why this matters: - Catches format issues before they multiply across 30+ files - Validates approach matches user needs early - Adjusts course when cheap (chapter 1) vs expensive (chapter 8) - Prevents 5+ hours of rework Approximate time budget for a typical academic course (10 chapters): chapter 1 ~30 min, review ~15 min, remaining ~90 min, QA ~30 min = ~2.5 hours vs 80+ hours manual. Pattern is greenfield-build universal; applies equally to paper/book/codebase-docs generation. ## Multi-vault layout (when applicable) Many PKM users run more than one vault: a personal/manual vault (off-limits to agents) plus a Claude-native vault (default agent target). When the user has both, default writes target the Claude-native vault unless they explicitly extend access to the personal one. Specific paths and override env vars belong in the user's `CLAUDE.md`, not in this skill, so the skill stays portable. For strong off-limits enforcement on the personal vault, consider a structural enforcement hook at the agent boundary that blocks Write/Edit/Bash mutations targeting paths under the personal vault. ## Foundation plugins (summary) Install only what's needed; soft cap ~10 active plugins. Core set: - **Local REST API** — base layer for Claude Code <-> vault interaction (loopback HTTPS + bearer token) - **Obsidian Git** — auto-commit + push to private remote (real backup tier) - **Templater** — automation foundation for templates/scripts - **Daily Notes** (core) — daily scaffolding baseline - **Style Settings** — theme customization without CSS - **QuickAdd** — macros + capture pipelines - **Smart Connections** (multilingual caveats apply) — passive sidebar discovery via local embeddings - **Bases** (core) — replaces ~70% of Dataview use cases Detailed plugin notes (Calendar/Periodic Notes status, Smart Connections multilingual swap, AI-layer plugin caveats): see `references/plugins.md`. ## Claude Code <-> vault interaction patterns (summary) Five patterns, ordered by complexity: 1. Read directly via filesystem (Read tool) 2. Vault search via `obsidian.com` CLI (index-aware) 3. Local REST API direct (curl) 4. Bases queries (dashboards) 5. External tool to embed (PNG/SVG for complex viz) Per-pattern details + CLI mapping table + multi-vault notes: see `references/interaction-patterns.md`. ## Diagram tool selection (summary) Mermaid is default for universal compatibility. When it hits a limit, the alternatives table covers Excalidraw, Draw.io, PlantUML, D2, Pikchr, WaveDrom, Kroki, TikZ, Python+Matplotlib. Tool selection factors: concept complexity, precision, platform priority, editability, time, dynamic-vs-static, version control. Full table + decision tree + selection factors: see `references/diagrams.md`. ## File-format philosophy Files are file-portable by definition (markdown, txt, universal formats). Apps are transient tools; data is permanent. Use any Obsidian feature freely (wikilinks, transclusions, callouts, highlights, comments, Dataview/Bases queries). Caveat: don't let a Dataview/Bases query be the only home of a fact. The query result is Obsidian-only; the underlying notes are portable. ## Methodology choice | Pick | When | Free source | |---|---|---| | Evergreen Notes (Matuschak) | Knowledge work, 2+ year horizon | notes.andymatuschak.org | | Zettelkasten (Doto) | Long-form output (books/papers) | writing.bobdoto.computer | | LYT/Ideaverse (Milo) | Original synthesis with MOCs | linkingyourthinking.com | | PARA (Forte) | Output-driven projects | fortelabs.com | ## Backup discipline Obsidian Sync's 30-day version history is NOT backup. For real backup: 1. `git init` in vault root 2. `.gitignore` for `.obsidian/workspace*`, `.obsidian/cache*`, `.obsidian/plugins/*/data.json` (plugin credentials), `.smart-env/`, `.trash/` 3. Auto-commit on session close (or scheduled) 4. Push to a private remote (GitHub private repo, or self-hosted) 5. Periodic restore drill: clone the remote into a scratch dir, verify content matches expectation. A backup that has never been restored is hope, not backup. ## Common rendering pitfalls (summary) Recurring issues when generating markdown for an Obsidian vault: Mermaid node-label syntax, LaTeX pipes in tables, wiki-link vs markdown-link conventions, collapsible callouts for active-learning content, universal-features discipline (mobile + future-proofing), structural-consistency patterns 5-8 (navigation/objectives/TOC/cross-refs), systematic fix approach (grep all -> fix all -> re-grep -> document), and minor unicode/table/HTML-tag pitfalls. Full content + diagnose+fix recipes + universal-vs-platform feature table: see `references/rendering-pitfalls.md`. ## Anti-patterns - Plugin bloat (>10 active without startup measurement) - Structure paralysis (weeks reorganizing folders, zero notes written) - MOC paralysis (empty MOCs created preemptively) - Daily-Note-only vault (365 daily notes, zero permanent notes) - Sync-only backup (Obsidian Sync history is NOT backup; use obsidian-git as second tier) - Dataview/Bases query as the only home of a fact - Disabling Restricted Mode without an obsidianpluginaudit.com check - File-dropping plugins from GitHub releases without surfacing the trust escalation (bypasses both store review and BRAT vetting) - Committing `.obsidian/plugins/*/data.json` to git (often contains plaintext credentials) - Sending non-ASCII bodies via REST API PUT without explicit UTF-8 charset header (causes U+FFFD corruption) - Recommending Smart Connections for multilingual content without first swapping to a multilingual embedding model ## Asset organization Two patterns are in active community use; neither has clear consensus as the "right" one: - **Per-project**: `/assets/` for diagrams/images, `/code/` for samples. Relative paths (`![[../assets/x.png]]`) keep the project portable. Best for project-as-unit thinking and easy git submodule. - **Flat attachment folder**: Obsidian's default; single `attachments/` (or configured equivalent) at vault root, all paste-images go there. Best for cross-cutting reuse and simpler image-management. Pick based on portability needs (per-project wins) vs cross-vault reuse (flat wins). Avoid absolute paths in either pattern. For vaults that grow, the standard PKM structure scales: ``` vault/ Projects// notes/ assets/ # diagrams, images code/ # example code Resources/ # textbooks, papers, reference PDFs Daily-Notes/ Templates/ ``` Tag by concept rather than by location (`#async-patterns` not `#nodejs-folder`). Properties for metadata (`status`, `created`, `tags`). Bases queries for dynamic overviews on top of the static folder structure. For academic-study vault scaffolds (different shape, 00-overview / 01-chapter / cross-chapter / mock-exams): see `references/academic-vault.md`. ## When NOT to use Obsidian - Team collaboration: Notion - Daily journaling + outlining primary: Logseq - Already in Emacs: Org-mode/Org-roam - Mac with heavy PDF workflow: DEVONthink + Obsidian split - VS Code minimal-tooling: Foam/Dendron - Spatial-narrative thinking: Tinderbox ## Additional resources ### Reference files For detailed content beyond the summaries above: - **`references/plugins.md`** — Foundation plugins, AI-layer plugins (caveats), Smart Connections multilingual swap - **`references/interaction-patterns.md`** — Patterns 1-5 in detail + Manual-vs-CLI mapping table - **`references/diagrams.md`** — Full diagram tool table + decision tree + selection factors - **`references/rendering-pitfalls.md`** — Mermaid/LaTeX/wiki-link/collapsibles/universal-features + structural-consistency patterns 5-8 + systematic fix approach - **`references/academic-vault.md`** — Academic study vault scaffold + per-chapter trio + content patterns (navigation/objectives/applied-understanding) + comprehensive coverage + CLAUDE.md layering - **`references/qa-checklist.md`** — 50+ item QA checklist for declaring chapters/sections complete (content/format/structure/quality) + CLI verification commands + project template - **`references/voice-capture-macro.md`** — QuickAdd + ElevenLabs MCP voice-memo-to-daily-note macro (working implementation as of 2026-05-15) ## Status v0.2.0 (2026-05-23 restructured per canonical agent-skills spec: <500 lines + companion docs in `references/` subdirectory). Patterns are the result of a research arc with multi-wave agent verification, end-to-end mobile sync test, and Smart Connections empirical multilingual evaluation. NOT yet validated by an external full PKM build. Bump to v1.0 only after that lands. The previously-separate `obsidian-study-vault-builder` skill (battle-tested across 37-file/828KB academic study vaults) was deprecated 2026-05-15 per PR #6 + post-compact re-validation. Its durable patterns are folded into this skill (`references/academic-vault.md` + `references/qa-checklist.md` + `references/rendering-pitfalls.md` § structural-consistency).