Obsidian Vault Builder

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

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: <project>/assets/ for diagrams/images, <project>/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/<project-name>/
    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).

Academic study vault scaffold (course prep + exam-ready content)

For course-prep vaults (lecture notes, exam-ready material, mock exams), the standard PKM scaffold is wrong shape. Use this proven scaffold instead. Folded from the deprecated obsidian-study-vault-builder skill 2026-05-15; battle-tested on 37-file/828KB academic vaults.

Standard study vault structure

course-name/
├── 00-overview/              # Course map, schedule, exam strategy
│   ├── course-map.md         # Master TOC: chapters + cross-chapter links
│   ├── schedule.md           # Lecture/assessment dates
│   └── exam-strategy.md      # Topic priorities, instructor patterns
├── 01-chapter-name/          # One folder per chapter
│   ├── core-concepts.md      # Comprehensive guide (20-50KB)
│   ├── quick-ref.md          # Condensed summary (2-5KB)
│   └── practice-problems.md  # 10 problems + collapsible solutions
├── 02-chapter-name/          # Same per-chapter trio
├── cross-chapter/            # Topic comparisons that span chapters
│   ├── pattern-catalog.md    # Reusable patterns
│   └── exam-style-mapping.md # Which patterns appear in which exam style
└── mock-exams/               # Past papers + simulated tests
    ├── 2026-midterm-1.md
    └── 2026-final-practice.md

Why this shape:

• 00-overview/course-map.md is the entry point; every chapter file links back here
• Per-chapter trio gives three reading depths (deep / quick / applied)
• cross-chapter/ lifts comparisons out of any single chapter (they belong to none)
• mock-exams/ is the rehearsal layer for exam-style alignment

Per-chapter file structure (universal)

Each 01-chapter-name/ follows this pattern. The structure is required for the cross-chapter cross-references in patterns above to work consistently.

`core-concepts.md` must contain (in order): 1. Title: # Chapter X: Name 2. Navigation: [[../00-overview/course-map|← Back]] | [[quick-ref|Quick Ref →]] 3. Divider: --- 4. Learning Objectives: ## Learning Objectives (COX) block 5. Divider: --- 6. Table of Contents: ## Table of Contents (if file >500 lines) 7. Content sections with examples 8. Cross-references to other chapters

`quick-ref.md` must contain: 1. Title + navigation back to core-concepts.md 2. Condensed key concepts (no examples, no explanations — just what + when) 3. Quick-lookup tables (complexities, formulas, rules)

`practice-problems.md` must contain: 1. Title with chapter name 2. Navigation links back to core-concepts.md and quick-ref.md 3. Overview section 4. Table of Contents (if >10 problems) 5. Problem sets grouped by type 6. All solutions in collapsible callouts (> [!example]-)

Academic content patterns

Three patterns universal for any course-prep vault:

Navigation link pattern

Every chapter file starts with the same shape, providing reader orientation:

# Chapter Title

[[../00-overview/course-map|← Back to Course Map]] | [[quick-ref|Quick Reference →]]

---

Rules:

• Always provide a way back to course map (anchor of the vault)
• Link to sibling files (quick-ref, practice)
• Use relative paths from current location
• Test links work via obsidian.com unresolved after creating

Learning objectives pattern (CO mapping)

University courses typically map to Course Outcomes (CO1, CO2, ...). Tie each chapter to its CO so the vault doubles as an exam-prep matrix:

## Learning Objectives (CO4)

> [!note] Course Outcome CO4
> **Compose problem-solving approaches to solve problems**
>
> By the end of this chapter, you should be able to:
> - Identify problems suitable for divide-and-conquer
> - Apply the algorithm with correct complexity analysis
> - Compare divide-and-conquer vs dynamic-programming trade-offs

For non-university content (textbook chapters, self-study), substitute "Learning Objectives" without the CO label.

Applied understanding (not memorization)

Practice problems should test application, not recall. Question patterns that work:

• "Design [system] for [context]. Current [problem]. Describe solution to achieve [goal]. Analyze trade-offs and justify."
• "Given [scenario], which algorithm is appropriate and why? Compare against the alternative."
• "Trace [algorithm] on [input], showing state at each step."

Adapts to subject domain:

• CS: Algorithm design scenarios
• Medicine: Case-based diagnosis
• Business: Strategic analysis
• Physics: Experimental design
• Math: Proof-construction or counterexample

Avoid: "Define X." "What is Y?" "List the steps of Z." These test memorization, fail to predict exam performance, and bore the student.

Comprehensive coverage principle

Every topic from source materials must appear in the vault. Coverage gaps cause exam-day surprises. Validation:

1. Extract source outline (textbook TOC, syllabus, lecture index) 2. Cross-reference against vault TOC 3. Diff produces gap list 4. Build out the gaps before declaring "complete"

Concrete: comm -23 <(sort source-outline.txt) <(sort vault-toc.txt) returns topics in source NOT in vault.

CLAUDE.md layering within a vault

Per the official Claude Code memory model (https://code.claude.com/docs/en/memory), CLAUDE.md files are loaded by walking up the directory tree from cwd; all discovered files concatenate into context (they don't override each other). Subdirectory CLAUDE.md files lazy-load when Claude reads files there.

Practical application for vaults spanning multiple knowledge domains: layer CLAUDE.md files at appropriate depths.

• Vault-root CLAUDE.md: vault conventions (folder structure principles, universal-features discipline, plugin philosophy, naming rules)
• Category folder CLAUDE.md (e.g., Projects/CLAUDE.md, Reference/CLAUDE.md): domain-specific patterns
• Project folder CLAUDE.md: project-specific facts (deadlines, collaborators, source materials)

Official guidance recommends keeping each CLAUDE.md under 200 lines. For path-scoped rules, .claude/rules/*.md with paths frontmatter is an alternative to nested CLAUDE.md.

Diagram tool selection (beyond Mermaid)

Mermaid is the default for universal compatibility. When it hits a limit, reach for one of these:

Decision tree

• Simple flowchart or sequence -> Mermaid
• Block / architecture / packet / sankey diagram -> Mermaid v11+ (added natively)
• Complex UML -> PlantUML (D2 plugin is stale; use the D2 language externally and embed PNG/SVG)
• Hand-drawn aesthetic -> Excalidraw (desktop) or external image
• Professional architecture -> Draw.io (offline variant) or D2 external
• Hardware timing diagram -> WaveDrom (verify plugin freshness or use the wavedrom CLI externally)
• Data visualization -> Vega/Charts plugin or Python -> PNG
• Quick sketch -> Excalidraw
• Algorithm trace -> Python (Matplotlib) -> PNG
• Mind map -> Mermaid mindmap (now stable post v11.4) or Canvas Mindmap
• Math notation -> LaTeX (always)
• Want one syntax for many formats -> Kroki (verify format support)

Tool selection factors

When picking among options, weigh:

• Concept complexity: simple -> Mermaid; complex -> external tool
• Precision needed: rough -> Excalidraw; exact -> D2 or PlantUML
• Platform priority: mobile-important -> universal formats only; desktop-only -> full toolset
• Editability: frequent updates -> text-based (Mermaid, D2); one-time -> image acceptable
• Time available: quick -> Mermaid or Excalidraw; detailed -> external generation
• Dynamic vs static: data-driven -> programmatic (Vega, Python); static -> diagram tool
• Version control: text-based formats track in git cleanly; binary needs Git LFS for size

Claude Code <-> Obsidian vault interaction patterns

Five patterns, increasing complexity. Pick by the operation, not by preference for one tool.

Pattern 1: read directly via filesystem

Most reads: use the Read tool. Pull the vault path from the user's CLAUDE.md rather than hardcoding.

Pattern 2: vault search via obsidian.com CLI

Useful for index-aware operations:

obsidian.com search query="<text>"
obsidian.com unresolved          # broken wiki-links
obsidian.com tags counts         # tag inventory
obsidian.com property:set name=<key> value=<val> path=<file>

Manual-vs-CLI mapping (prefer CLI when index-aware semantics matter):

Multi-vault: obsidian.com --vault=<name> <subcommand> targets a specific vault. Useful when more than one vault is open or when scripting across vaults.

Universal escape hatch: obsidian.com command id=<command-id> executes any registered Obsidian command (including plugin commands). obsidian.com commands lists all available command IDs. CLI also has subcommands for bases, publish:*, sync:*, quickadd:*, templater:*, snippets, themes, hotkey, hotkeys; see obsidian.com help for the full ~100-command catalog.

Pattern 3: Local REST API direct (curl)

Skip community MCP wrappers; most are stale or archived. Curl directly:

curl -H "Authorization: Bearer $OBSIDIAN_REST_API_KEY" \
  https://127.0.0.1:27124/vault/path/to/note.md

For production use, install the self-signed cert into the OS trust store rather than passing -k everywhere. Cert is downloadable via the "this certificate" link in Local REST API plugin settings.

Pattern 4: Bases queries

For new dashboards prefer Bases over Dataview (lighter, core, mobile-friendly):

where status = "active" AND priority = "high" AND due >= 2026-05-01

Pattern 5: external tool to embed (PNG/SVG)

When a visualization exceeds Mermaid's expressiveness (algorithm traces, statistical plots, network diagrams, publication-quality figures), generate externally and embed:

• Python: Matplotlib, NetworkX, Seaborn, drawsvg, CairoSVG
• Graphviz/DOT for graph hierarchies
• TikZ (LaTeX) for publication-quality technical diagrams
• D3.js / Plotly for data-driven (export static for vault)

Workflow: create externally, save as PNG/SVG to <project>/assets/, embed via ![[../assets/asset.png]]. Use relative paths so the vault stays portable across re-orgs.

Obsidian plugins (foundation + AI-layer + Smart Connections multilingual)

Foundation plugins

These are in Obsidian's official community plugin store. Install only what's needed:

1. Local REST API (coddingtonbear): base layer for Claude Code <-> vault interaction. HTTPS bearer token; store the key in a password manager. Loopback-only on 127.0.0.1:27124. 2. Obsidian Git: auto-commit on a schedule, push to a private remote. Note: Obsidian Sync's 30-day version history is NOT a backup; this is. 3. Templater: automation foundation for templates and user scripts. 4. Daily Notes (core, no install): maintained baseline for daily scaffolding. The companion Calendar plugin (liamcain/obsidian-calendar-plugin) is ~23 months stale (same author-abandonment pattern as Periodic Notes); still functional but no fixes incoming. For weekly/monthly/quarterly/yearly scopes, Periodic Notes (liamcain/obsidian-periodic-notes) is the only widely-used option; ~21 months stale but still functional. Bases-based date views (querying frontmatter date properties) can replace Calendar's sidebar UI for many users. luiisca/obsidian-periodic-notes-calendar is a smaller, actively-maintained alternative combining both. Templater handles custom periodic-note generation for setups that outgrow Periodic Notes. 5. Style Settings: theme customization without writing CSS. 6. QuickAdd: macros and capture pipelines. 7. Smart Connections (brianpetro/obsidian-smart-connections): passive sidebar discovery via local embeddings (free). Note: 475+ open issues and a paywalled v4 have driven users to forks; consider logancyang/obsidian-copilot as an alternative or co-primary AI-layer plugin (6.9k+ stars, broader model support including Claude/Gemini/local). 8. Bases (CORE built-in, no install required): replaces ~70% of Dataview use cases.

Plugin-bloat discipline: ~10 active plugins as a soft cap. Anything beyond requires a startup-time measurement before/after to confirm acceptable launch latency.

AI-layer plugins (caveat-heavy)

Several Claude/Codex-integrating plugins exist with varying vetting status. Always verify current store-listing status before recommending:

• Agent Client (RAIT-09/obsidian-agent-client, registry id agent-client): multi-agent flexibility (Claude/Codex/Gemini via standardized ACP). Verified in official store as of 2026-05-15. Store-installable.
• Claudian (YishenTu/claudian, plugin id realclaudian): GUI alternative to terminal Claude Code. NOT in official store as of 2026-05-15; BRAT install only. Verify status before recommending.
• ObsidiBot (formerly Cortex; ScottKirvan/ObsidiBot): Claude Code chat panel inside Obsidian. NOT in official store as of 2026-05-15; BRAT install only. Verify status before recommending.
• Exclude m-rgba/obsidian-ai-agent: archived 2026-04.

Apply the "does this add capability beyond Claude Code reading the vault directly?" test per-plugin. For terminal Claude Code users, the test usually returns "no" for these. Default-skip; install only on explicit user request after surfacing the trust escalation (file-drop or BRAT installs run with full vault read/write/bash access).

Smart Connections language coverage

Smart Connections ships with an English-only default embedding model. For multilingual vaults (Arabic, Hebrew, CJK, etc.), the default model produces near-noise similarity scores on out-of-distribution content.

Recommended path (UI): open Smart Environment settings in Obsidian. The Default embedding model dropdown lists 3 transformers-compatible options labelled "BGE-micro-v2 (fastest)", "Multilingual E5 Small", "Snowflake Arctic Embed XS (fast)". Internally these resolve to Xenova-hosted ONNX-quantized variants (Xenova/multilingual-e5-small, etc.). For Arabic / Hebrew / CJK content, pick "Multilingual E5 Small". Click Test model to download (the Test button may transiently report "Message adapter unloaded" but the actual embedding pipeline still works). Then click Reset data + Re-import to regenerate embeddings.

Direct-JSON swap path (NOT recommended, error-prone): the active model is determined by <vault>/.smart-env/smart_env.json's embedding_models.default_model_key field, which references an entry in <vault>/.smart-env/embedding_models/embedding_models.ajson registry. The smart_sources.embed_model.transformers.model_key field is set during UI swaps but appears unused as the source of truth. The registry file is append-only ajson; multiple entries with the same key are tolerated (last-wins semantics). The plugin loads via transformers.js which fetches huggingface.co/<model>/resolve/main/onnx/model_quantized.onnx; models without an ONNX-quantized variant at that exact path fail. Tested 2026-05-15: BAAI/bge-m3 fails (no Xenova ONNX variant). For Pro-tier providers (LM Studio, Ollama, OpenAI, Gemini, OpenRouter) the JSON shape is different per provider. Prefer the UI path; the JSON format isn't a stable API.

For long-term setups, prefer the UI dropdown with a documented model. Verify multilingual coverage empirically before relying on it for production search.

Vault QA Checklist (companion to obsidian-vault-builder/SKILL.md)

Use before declaring a chapter / section / vault "complete." The CLI verifications below replace manual grep-based checks when the Obsidian app is running. Fall back to grep/manual when the app is closed.

Content

• [ ] Every topic from source materials covered (cross-reference source outline against vault TOC)
• [ ] All key concepts explained with examples (no "TODO: add example" stubs)
• [ ] Complexity / cost / trade-off analysis included where domain applies
• [ ] Cross-references to related chapters present and resolving

Format

• [ ] Navigation links present and working at the top of every main file
• [ ] Learning objectives stated (and CO-mapped if academic)
• [ ] Table of contents present for any file >500 lines
• [ ] All Mermaid diagrams render (preview them in Obsidian, not just markdown)
• [ ] All LaTeX formulas correct (inline $...$ and block $$...$$ render)
• [ ] All internal wiki-links resolve (obsidian.com unresolved returns clean)
• [ ] Collapsible solutions in practice files work ([!example]- form, blank line after marker)

Structure

• [ ] Follows the standard file organization (see SKILL.md "Academic study vault scaffold" or PKM scaffold)
• [ ] Naming conventions consistent (kebab-case, no spaces in filenames)
• [ ] File paths correct (relative paths for portability)
• [ ] Mobile-compatible features only for shared content

Quality (assessment alignment)

• [ ] Practice problems test application (not memorization — see SKILL.md "Applied understanding")
• [ ] Solutions show step-by-step reasoning, not just final answer
• [ ] Examples are clear and complete (a fresh reader can follow)
• [ ] No gaps in explanations (no "and you can show that..." hand-waves)

CLI verification commands (run after build)

Requires Obsidian app running. Falls back to grep/manual if app is closed.

Anti-patterns to avoid (final pass)

• Don't add features "because they're nice" — summary sections where not needed, exam-prep sections when a dedicated file exists, "standardizing" content that should vary by topic
• Don't assume consistency without checking — spot-checking 2 files doesn't guarantee all 8 match; different file types may have different patterns; user edits may have shifted some files since generation
• Don't batch completions — marking 3 todos complete at once looks like you forgot; update progress as you go
• Don't create AI slop — unnecessary praise, over-the-top validation, emoji overuse, bloated summaries
• Don't break elegance for features — quick-ref files naturally vary by content; not everything needs tables; simple beats complex

Project template (reusable initial prompt structure)

When kicking off a new course-prep vault build, give the agent this context shape:

COURSE CONTEXT:
- Course name and code
- Textbook and chapters ACTUALLY covered
- Exam timeline
- Assessment format and style

MATERIALS LOCATION:
- Folder structure
- File types (slides, textbook, assignments, lecture transcripts)
- Reference guides (visualization standards, course outcomes)

OBJECTIVES:
- Deep understanding (applied, not memorization)
- Comprehensive coverage (no gaps from source outline)
- Organized study system

QUALITY CONTROL:
Checkpoint-based (per SKILL.md):
1. Complete chapter 1 fully
2. STOP and show what was created + sample outputs + verification checklist
3. Wait for approval
4. Continue with brief status updates per chapter

FILE STRUCTURE:
Use SKILL.md "Academic study vault scaffold" + per-chapter trio.

FORMATTING STANDARDS:
- Follow visualization guide
- Universal Obsidian features only (no plugin-dependent rendering for shared content)
- Mobile-compatible

Common Obsidian rendering pitfalls (writing markdown to a vault)

When generating markdown content for an Obsidian vault, these are the recurring rendering issues. Patterns extracted from a deprecated companion skill (obsidian-study-vault-builder, removed via PR #6 and re-validated 2026-05-15: over-triggered on exam-prep prompts and was structurally misaligned with the interactive-practice approach). The durable patterns below apply to ANY agent writing markdown to a vault, not just academic builds.

Mermaid diagrams

• [1. Text] triggers "Unsupported markdown: list" error in node labels. Use ["Step 1:<br/>Text"] (quoted with HTML break).
• [text](value) inside node labels is interpreted as link syntax. Use {text}(value) (curly braces).
• Special-character parsing edge cases persist in some Mermaid v11.x diagram types (sankey, etc.). For mindmap & (Mermaid issue #6308) and mindmap </> (issue #6396), both fixed in v11.4+ and current Obsidian (1.12.x) bundles a fixed version. Older Obsidian releases may still need ASCII <=/>= substitution and Unicode fullwidth ＆ workaround.
• Diagnose via grep -r "≤\|≥\|∞\|∈\|≠" *.md if targeting older Obsidian.

LaTeX in markdown tables

Pipe characters | in LaTeX break markdown table parsing.

| Algorithm | Complexity |
|-----------|------------|
| DFS       | $\Theta(\|V\| + \|E\|)$  | <- escaped pipes

Search pattern: grep -r "| \\$.*|.*\\$" *.md to find unescaped pipes inside LaTeX inside table cells.

Wiki-link vs markdown-link conventions

For internal vault navigation, use wiki-link form, NOT markdown link form:

• Same-file section: [[#Section Name]] (NOT [Section](#section))
• Other-file section: [[file#Section Name]]
• Display text override: [[file|Display Text]]
• Relative path to parent: [[../folder/file]]

Markdown links to internal sections often break in Obsidian's renderer; wiki-links resolve via the link index.

Collapsible callouts for active-learning content

For any content where the reader should attempt before seeing the answer (practice problems, quiz questions, exercises), use a collapsible callout:

### Problem 1: Title

**Question:** Statement here.

> [!example]- Solution
>
> **Approach:** strategy
>
> **Algorithm:** step-by-step
>
> **Complexity:** analysis

The - after [!example] makes it collapsible (default collapsed). Blank line after the marker is required; subsequent lines must continue with > prefix.

Universal-features discipline (mobile + future-proofing)

For long-lived shared content, prefer the universal set; use plugin-dependent features for personal dashboards only.

Mobile vault sizing: with Obsidian 1.10+ progressive loading, vaults of 10k+ notes start under 1 second on phones (Kepano demo'd 17k+ notes). The older 3-4k file limit was a pre-1.10 artifact. Plugin count is the higher driver of mobile startup latency than file count today; soft cap of ~10-15 active plugins remains a good discipline.

Document platform dependencies inline

When generating notes that depend on desktop-only features, prepend a Platform Notes callout so future-readers know what works where:

> [!info] Platform Notes
> **Desktop**: Full Excalidraw editing, Dataview queries, Canvas multi-pane.
> **Mobile**: Static diagram exports, markdown tables, core callouts.
> **Plugins**: Excalidraw, Dataview (optional; richer experience).

Structural-consistency error patterns (5-8)

Patterns 1-4 above are content-rendering errors. Patterns 5-8 are structural-consistency errors that surface when many files are generated. Each carries a diagnose + fix recipe:

• Pattern 5: Inconsistent navigation across files. Some files have [[← Back]] | [[Quick Ref →]] headers, others don't. Diagnose: grep -L "← Back" 01-*/core-concepts.md (lists files WITHOUT the marker). Fix: apply the navigation-link pattern (see academic-vault.md) to every file. Verify: re-grep returns empty.
• Pattern 6: Missing learning objectives. Some chapter files lack the ## Learning Objectives (COX) block tying to course outcomes. Diagnose: grep -L "## Learning Objectives" 01-*/core-concepts.md. Fix: add the callout per the pattern.
• Pattern 7: Inconsistent table of contents. Files >500 lines need a TOC; smaller files don't. Diagnose: for f in *.md; do lines=$(wc -l < "$f"); if [ "$lines" -gt 500 ] && ! grep -q "## Table of Contents" "$f"; then echo "$f"; fi; done. Fix: add TOC.
• Pattern 8: Broken cross-references. Wiki-links to other chapters fail. Diagnose: obsidian.com unresolved. Fix: convert markdown links to wiki-link form; verify with obsidian.com search for the target heading text.

Systematic fix approach (for any consistency error)

When one instance of an inconsistency surfaces, others almost always exist. The diagnose-once, fix-one approach is a trap:

1. Grep all — find every file matching the broken pattern, NOT just the one user flagged 2. Fix all — apply the corrected pattern across all matches in one pass 3. Re-grep — verify zero remaining matches 4. Document — add the diagnose+fix to memory so the next session doesn't re-derive it

Evidence: study-vault-builder arc found that user reports of "this file looks wrong" were almost always tip-of-iceberg; 1 user-flagged file -> 4-8 sibling files with the same issue. Spot-fixing required a third round trip. Greedy-grep avoids the loop.

Other rendering pitfalls

• Unicode `?` chars in rendered text: usually a source-app encoding issue (Windows cp1252 vs UTF-8 in the clipboard pipeline) rather than Obsidian itself. Re-encode the source or copy through a UTF-8-aware intermediary.
• Broken tables (missing blank line): pipes/dashes render as literal text. Fix: ensure ONE blank line before any markdown table.
• HTML details/summary tags don't render in Obsidian: don't use <details>/<summary>; use the > [!example]- callout form documented above.

QuickAdd Macro: Voice Capture → Daily Note

This is a template guide for setting up a QuickAdd macro that takes a voice memo file, transcribes it via your existing ElevenLabs MCP (through Claude Code), and appends the transcript to today's daily note in obsidian-claude.

Dependencies

• QuickAdd plugin (chhoumann, 2,209 stars, active): install in Obsidian
• Templater plugin (SilentVoid13, 4,933 stars, active): install in Obsidian
• Claude Code installed and accessible from PATH
• ElevenLabs MCP already configured at ~/.claude.json (verified present in user's config)

Two implementation paths

Path A: recommended (Claude Code shells out to ElevenLabs MCP)

QuickAdd macro chain: 1. UserScript: pickVoiceFile: file picker for .m4a/.mp3/.wav returning filepath 2. UserScript: transcribeVoice: invokes Claude Code with prompt to transcribe via ElevenLabs MCP 3. Capture: appends transcript to Daily Notes/{{date:YYYY-MM-DD}}.md under ## Voice memo {{time:HH:mm}} heading

Path B: standalone (Templater calls ElevenLabs API directly)

Same chain but step 2 calls ElevenLabs API direct: requires API key in Templater settings (already in Proton Pass as ElevenLabs Claude Code per user's setup).

User-function templates

Save these in a vault-root folder (e.g., ~/obsidian-claude/scripts/), NOT inside `.obsidian/`. QuickAdd v2.x explicitly rejects scripts inside .obsidian/ (verified 2026-05-15 against chhoumann/quickadd:src/gui/MacroGUIs/noScriptsFoundNotice.ts — the error message says: "In your vault (not in .obsidian folder), Not in hidden folders (starting with a dot), Have a .js extension"). Templater scripts CAN live inside .obsidian/scripts/, but QuickAdd User Script steps cannot. If you want both Templater and QuickAdd to use the same .js, put it at the vault root.

pickVoiceFile.js (QuickAdd User Script signature, NOT Templater)

// QuickAdd User Script: file picker for voice memos.
// Returns the picked file's vault-relative path (becomes {{VALUE}} for next step
// AND saved to params.variables.voiceFilePath for downstream scripts).
//
// Verified 2026-05-15 against chhoumann/quickadd:src/quickAddApi.ts:
//   - User Scripts receive `params = { quickAddApi, app, variables, ... }`
//   - quickAddApi.suggester(displayItems, actualItems) returns the picked actualItem
//
// IMPORTANT: NOT a Templater user function. Templater would pass `tp` and have
// `tp.system.suggester`; QuickAdd passes `params` and uses `quickAddApi.suggester`.
// The two plugins have different script signatures even though both load .js files.
module.exports = async (params) => {
  const { quickAddApi, app, variables } = params;

  const audioFiles = app.vault.getFiles().filter((f) =>
    ["m4a", "mp3", "wav", "ogg", "webm", "flac"].includes(f.extension)
  );

  if (audioFiles.length === 0) {
    new Notice("pickVoiceFile: no audio files in vault");
    return null;
  }

  const picked = await quickAddApi.suggester(
    audioFiles.map((f) => f.path),
    audioFiles
  );

  if (!picked) return null;
  variables.voiceFilePath = picked.path;
  return picked.path;
};

transcribeVoice.js (uses execFile not exec; QuickAdd User Script signature)

// QuickAdd User Script: transcribe voice memo via Claude Code + ElevenLabs MCP.
// Reads filepath from params.variables.voiceFilePath (set by pickVoiceFile).
// Returns the transcript text, which becomes {{VALUE}} for the Capture step.
//
// Verified 2026-05-15:
//   - Binary is `claude` (NOT `claude-code`); flag is `-p "<prompt>"` (NOT `--prompt`).
//     Find your binary's full path with `where claude` (Windows) or `which claude` (Unix).
//   - QuickAdd's spawned subprocess env may not have ~/.local/bin on PATH; use full path.
//   - ElevenLabs MCP must be reachable from the spawned Claude process; verified
//     present in ~/.claude.json for the original setup.
module.exports = async (params) => {
  const { quickAddApi, app, variables } = params;

  const filepath = variables.voiceFilePath;
  if (!filepath) {
    new Notice("transcribeVoice: no filepath in variables. Run pickVoiceFile first.");
    return null;
  }

  const path = require("path");
  const vaultRoot = app.vault.adapter.basePath || app.vault.adapter.getBasePath?.() || "";
  const absPath = vaultRoot ? path.join(vaultRoot, filepath) : filepath;

  const prompt =
    `use elevenlabs MCP to transcribe "${absPath}" and return ONLY the transcript text. ` +
    `no commentary, no preamble, no markdown formatting, no quotes around the text.`;

  const { execFile } = require("child_process");
  const { promisify } = require("util");
  const execFileAsync = promisify(execFile);

  // Replace with the absolute path your `where claude` / `which claude` returns.
  const claudeBin = "C:/Users/<you>/.local/bin/claude.exe";

  try {
    new Notice("transcribeVoice: invoking Claude + ElevenLabs MCP (may take 30s-2min)...");
    const { stdout, stderr } = await execFileAsync(claudeBin, ["-p", prompt], {
      maxBuffer: 10 * 1024 * 1024,
      timeout: 120000,
    });

    const transcript = stdout.trim();
    if (!transcript) {
      new Notice("transcribeVoice: empty transcript returned");
      if (stderr) console.warn("claude stderr:", stderr);
      throw new Error("empty transcript");
    }
  } catch (e) {
    new Notice(`transcribeVoice failed: ${e.message}`);
    console.error("transcribeVoice error:", e);
    throw e;
  }

  // DIRECT WRITE to today's daily note. Bypasses QuickAdd's NestedChoice +
  // Capture step, which doesn't auto-populate {{VALUE}} from the macro chain
  // (verified failure mode 2026-05-15: NestedChoice opens an empty input
  // prompt instead of consuming the prior script's return value).
  const now = new Date();
  const yyyy = now.getFullYear();
  const mm = String(now.getMonth() + 1).padStart(2, "0");
  const dd = String(now.getDate()).padStart(2, "0");
  const hh = String(now.getHours()).padStart(2, "0");
  const min = String(now.getMinutes()).padStart(2, "0");
  // Match Obsidian Daily Notes core-plugin defaults: YYYY-MM-DD.md at vault
  // root. If your daily-notes config uses a subfolder, prefix here.
  const dailyNotePath = `${yyyy}-${mm}-${dd}.md`;
  const block = `\n## Voice memo ${hh}:${min}\n\n${transcript}\n`;

  const file = app.vault.getAbstractFileByPath(dailyNotePath);
  if (file && file.path) {
    const existing = await app.vault.read(file);
    await app.vault.modify(file, existing + block);
  } else {
    await app.vault.create(dailyNotePath, block);
  }
  new Notice(`Voice memo appended to ${dailyNotePath} (${transcript.length} chars).`, 5000);
  return transcript;
};

IMPORTANT — macro structure for the direct-write variant: the macro should have only TWO commands: pickVoiceFile and transcribeVoice. Do NOT add a Capture step. The Capture-step path was tried and failed (QuickAdd wraps Capture in a NestedChoice when added inside a macro, and NestedChoice does NOT auto-populate {{VALUE}} from the macro's running value — it opens an empty input prompt instead). Direct vault-write from transcribeVoice is the verified-working path (validated 2026-05-15 with a 5MB / ~25-min audio file: 108s end-to-end).

QuickAdd macro configuration (set in plugin GUI; v2.x verified 2026-05-15 against chhoumann/quickadd:src/gui/choiceList/AddChoiceBox.svelte)

1. Open Obsidian, Settings, QuickAdd. There's no "Manage Macros" page in v2.x; macros are added as a Choice TYPE. 2. In the top "Choices and Packages" section: type Voice Capture in the Name field. 3. Click the type-selector dropdown (HTML <select>, defaults to displaying "Template") next to the Name field. The 4 options are Template, Capture, Macro, Multi. Pick Macro. 4. Click Add Choice (the purple mod-cta button). The macro appears in the choice list above. 5. Click the gear/settings icon next to "Voice Capture" in the choice list to open the macro configurator. 6. Inside the configurator, add EXACTLY two steps (do not add a Capture step): 1. Add, User Script then select pickVoiceFile from the file picker. 2. Add, User Script then select transcribeVoice. 7. Bind to ribbon icon or hotkey (e.g., Ctrl+Alt+V).

Testing checklist (Wave 4 empirical validation)

• [ ] Place a .m4a voice memo in obsidian-claude/Audio/
• [ ] Trigger Voice Capture macro
• [ ] File picker shows the memo
• [ ] Transcription completes within 2 minutes
• [ ] Transcript appended to today's daily note under correct heading
• [ ] No errors in DevTools console
• [ ] Source filepath included in append for traceability

Known caveats

• ElevenLabs MCP must be reachable from Claude Code's environment: confirmed present in ~/.claude.json
• 2-minute timeout is conservative for ElevenLabs Scribe v2; bump if your memos are >30 min
• Transcript is appended as-is; for cleanup (filler removal, paragraph breaks), chain a second Claude Code call

Status

TEMPLATE: install Phase 4 of `SOTA-PROPOSAL-v3.md` rollout. Empirical validation pending Wave 4. The user runs this once on obsidian-claude, verifies, then commits the working .js files to the vault git repo for portability.