obsidian-mcp

Vault operation safety layer for all Obsidian MCP operations. Load when any vault read/write/search/tag/edit/verify is needed. Do NOT use alone for workflow decisions; combine with companion skill.

SKILL.md

GitHub

obsidian-mcp

Constraints

  • NO write without fresh read first
  • NO completion claims without readback verification
  • EVERY changed line must trace to user request
  • This skill owns vault operations ONLY; workflow decisions belong to companion skills

Host Constraints (version-locked — re-verify on upgrade)

These are based on obsidian-mcp-server@3.1.5. They may be stale.

To re-verify: call the forbidden API with a trivial test payload. If it returns -32602, constraint holds. If it succeeds, update this table and remove the ban.

Operation Status Alternative
obsidian_patch_note Forbidden (last verified: 2026-05-10) obsidian_replace_in_note
obsidian_append_to_note Forbidden (last verified: 2026-05-10) obsidian_replace_in_note or obsidian_write_note overwrite:false for new files
obsidian_write_note overwrite:true Forbidden by default Surgical replace for existing files
obsidian_delete_note Requires user confirmation List path + risk first

If you suspect a constraint is stale, test it. A successful call means the ban should be lifted.

Tool Selection

Goal Tool
Browse structure obsidian_list_notes (depth 2-4)
Search obsidian_search_notes
Read before edit obsidian_get_note format:"document-map" then content/full
Create note obsidian_write_note overwrite:false → readback
Edit existing obsidian_replace_in_note → readback
Frontmatter obsidian_manage_frontmatter
Tags obsidian_manage_tags

When selecting tools, read references/examples.md for operation patterns.

Workflow

  1. Locate: identify targets, read before writing
  2. Plan: minimum change only; report unrelated issues, don't fix them
  3. Write: use appropriate tool from table above
  4. Verify: readback every write; compare actual vs expected

When formatting completion reports, read references/templates.md.

Error Recovery

Error Response
-32602 schema error Stop using that operation; switch to alternative
note_missing Search for candidates; ask user
file_exists Read existing; use surgical replace
3 repeated failures Stop and report

Trigger Boundary

Use when: any vault read/write/search/tag/edit/verify operation.

Do NOT use for: triage decisions, synthesis, relationship analysis, health diagnosis, promotion decisions — those belong to companion skills.

Boundaries

  • Owns: vault CRUD, frontmatter, tags, search, verification
  • Delegates to: all 6 workflow skills for decisions
  • Never absorbs: workflow decisions, knowledge interpretation

Continuations

Condition Next
Operation complete Return to calling workflow skill
Repeated MCP failures vault-health-feedback
3 failures on same op Escalate to human

Gotchas

Gotcha 1: Using forbidden APIs "because they look right" Current host fails with -32602 regardless of intent. Use alternatives. But if you suspect the bug is fixed, test it first.

Gotcha 2: Trusting section reads as verification format:"section" has schema issues on long content. Verify with content/full.

Gotcha 3: Making workflow decisions This skill executes operations, not decides what to do. Defer to companion skills.