Obsidian

Obsidian Vault Expert

The definitive skill for managing an Obsidian vault. Combines direct file operations (always available) with Obsidian CLI v1.12 (indexed graph queries) for a system that is both reliable and intelligent.

When to Use

• Create, read, edit, organize, or delete notes in the vault
• Find orphan notes, dead-end notes, or unresolved links
• Query backlinks, tags, properties, or tasks across the vault
• Run a vault health check or maintenance session
• Create notes from templates (Daily Note, Research Note, Project, etc.)
• Build or update Maps of Content (MOCs)
• Manage plugins (list, install, enable)
• Any question about the vault's structure, content, or graph

When NOT to Use

• Writing Obsidian plugins (TypeScript/plugin API) — use normal coding
• Content quality review or grammar checking
• Media transcription or lecture slide extraction
• Knowledge graph theory or visualization

Invocation

/obsidian                          # Interactive — asks what you need
/obsidian health                   # Full vault health check
/obsidian orphans                  # Find and fix orphan notes
/obsidian create research "Title"  # Create a research note from template
/obsidian search "query"           # Search vault content
/obsidian backlinks "note path"    # Find what links to a note
/obsidian tags                     # List all tags with counts
/obsidian daily                    # Create or append to today's daily note
/obsidian moc "Topic"              # Create/update a Map of Content
/obsidian plugins                  # List installed plugins

Architecture: The 3-Tier Hybrid Model

User: /obsidian [command] [args]
     |
     v
[Tier Selection] — Choose the right tool for the job
     |
     +---> CRUD (create, read, edit, delete, search content)?
     |       → Tier 1: Direct File Ops (Read/Write/Edit/Glob/Grep)
     |       → Always available, zero dependencies, instant
     |
     +---> Discovery (orphans, backlinks, tags, properties, indexed search)?
     |       → Tier 2: Obsidian CLI v1.12
     |       → Pre-check: pgrep -x Obsidian (must be running)
     |       → Binary: /Applications/Obsidian.app/Contents/MacOS/Obsidian
     |       → IMPORTANT: vault="$VAULT_NAME" MUST be first parameter
     |       → Fallback: Tier 1 (slower but functional)
     |
     +---> UI control (open note, trigger search panel)?
             → Tier 3: obsidian:// URI scheme
             → open "obsidian://open?vault="$VAULT_NAME"&file=..."

Vault Configuration

Every CLI command below uses vault="$VAULT_NAME", a shell variable you set once. Resolve the vault name and path with this order:

1. If $VAULT_NAME is already set in the environment, use it.
2. Otherwise, run obsidian vault list and prompt the user to pick one. Export

VAULT_NAME in the current shell so subsequent commands work.

1. For the absolute vault path, set $VAULT_PATH to the directory that contains

the .obsidian/ folder, or walk up from the current working directory until you find one.

The example "Vault Details" block below describes one possible vault layout — your PARA folder names, templates, and installed plugins will differ.

Vault Details (example)

• Path: $VAULT_PATH (set via env var, or detect by locating the .obsidian/ folder)
• PARA folders (example layout): 00 Inbox, 01 Projects, 02 Areas, 03 Resources, 09 Systems, 10 School, 99 Archive
• Templates (example, 12): in 09 Systems/Templates/ — Daily Note, Weekly Review, Project, Research Note, Literature Note, Company Research, Job Application, Learning Plan, Networking Log, Quant Prep, Skill Log, Template Index
• Installed plugins (example): terminal, calendar, templater-obsidian
• CLI version: 1.12.1

Domain Knowledge

Deep reference material lives in the spawner skill. Read these files for detailed patterns, sharp edges, and architectural decisions when needed:

~/.spawner/skills/creative/obsidian-cli/
├── skill.yaml           # Core definition, 13 patterns, 13 domains
├── patterns.md          # 11 pattern deep-dives with full examples
├── sharp-edges.yaml     # 15 pitfalls with detection patterns
├── sharp-edges.md       # 15 sharp edges with Why/Detect/Fix/Prevent
├── collaboration.yaml   # Ecosystem, prerequisites, handoffs
├── decisions.md         # 11 architectural decisions with rationale
├── anti-patterns.md     # 9 anti-patterns with bad/good examples
└── validations.yaml     # 16 quality gate checks

Read the relevant file when you need deep context on a specific topic.

Command Reference

/obsidian health — Full Vault Health Check

The canonical hybrid workflow. Uses CLI for fast discovery, file ops for fixes.

Step 1: Pre-flight checks
  - Verify Obsidian is running: pgrep -x Obsidian
  - Verify CLI responds: obsidian vault="$VAULT_NAME" version
  - If CLI unavailable, warn user and fall back to file-ops-only mode

Step 2: Discovery via CLI (Tier 2)
  - obsidian vault="$VAULT_NAME" orphans total        → count orphan notes
  - obsidian vault="$VAULT_NAME" deadends total       → count dead-end notes
  - obsidian vault="$VAULT_NAME" unresolved total     → count unresolved links
  - obsidian vault="$VAULT_NAME" tags all counts      → tag distribution
  - obsidian vault="$VAULT_NAME" tasks all todo total → open task count

Step 3: Structural analysis via file ops (Tier 1)
  - Glob each PARA folder to count notes per folder
  - Grep for notes missing frontmatter (no leading ---)
  - Grep for notes in vault root (should be zero)

Step 4: Report
  - Present findings as a markdown summary
  - Categorize issues by severity (critical, warning, info)
  - Offer to fix issues (add links to orphans, create missing notes, etc.)

Step 5: Fix (if user approves)
  - Use Edit to add [[links]] to orphan notes
  - Use Write to create stub notes for unresolved links
  - Use Edit to add frontmatter to notes missing it

/obsidian orphans — Find and Fix Orphan Notes

Step 1: CLI discovery
  obsidian vault="$VAULT_NAME" orphans
  → List of notes with no incoming links

Step 2: For each orphan, analyze with file ops
  - Read the orphan note
  - Identify its topic, tags, and content
  - Search for related notes that should link to it

Step 3: Suggest or apply fixes
  - Add [[links]] in related notes pointing to the orphan
  - Add the orphan to relevant MOCs
  - If the orphan is stale, suggest archiving to 99 Archive/

/obsidian create [type] "Title" — Create Note from Template

Supported types:
  research  → Research Note v1.md  → 03 Resources/
  project   → Project v1.md       → 01 Projects/
  daily     → Daily Note v1.md    → 00 Inbox/YYYY-MM-DD.md
  weekly    → Weekly Review v1.md  → 00 Inbox/
  literature → Literature Note v1.md → 03 Resources/
  company   → Company Research v1.md → 03 Resources/
  job       → Job Application v1.md → 01 Projects/
  learning  → Learning Plan v1.md  → 01 Projects/
  networking → Networking Log v1.md → 02 Areas/
  quant     → Quant Prep v1.md    → 10 School/
  skill     → Skill Log v1.md     → 02 Areas/

Step 1: Read the template from 09 Systems/Templates/
Step 2: Substitute Templater variables with actual values
  -  → current date
  -  → the provided title
Step 3: Check for existing file with Glob (prevent overwrite)
Step 4: Write the populated note to the correct PARA folder
Step 5: Optionally open in Obsidian via URI

/obsidian search "query" — Indexed Search

Step 1: If CLI available:
  obsidian vault="$VAULT_NAME" search query="[query]" limit=20
  → Fast indexed results in ` variables before writing; wrap in code blocks if documenting
8. **Wiki-links over markdown links** — use `[[Note Name]]` for all internal links

## PARA Folder Selection

| Content Type | Folder |
|-------------|--------|
| Active project with deadline | `01 Projects/` |
| Ongoing area of responsibility | `02 Areas/` |
| Reference material, topic | `03 Resources/` |
| Academic, coursework | `10 School/` |
| Quick capture, unsorted | `00 Inbox/` |
| Templates, dashboards, config | `09 Systems/` |
| Completed, inactive | `99 Archive/` |

## Performance Benchmarks

| Operation | CLI v1.12 | File Ops | CLI Speedup |
|-----------|-----------|----------|-------------|
| Orphan detection | 0.26s | 15.6s | 60x |
| Search | 0.32s | 1.6s | 5x |
| Backlinks | ~0.1s | Impossible* | -- |
| Tag aggregation | ~0.2s | ~3s | 15x |

*Backlink queries via file ops require scanning every file for `[[target]]`, missing aliases.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ZealousEar](https://github.com/ZealousEar)
- **Source:** [ZealousEar/claude-skills](https://github.com/ZealousEar/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.