obsidian

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: obsidian
description: >
  Activate when the user mentions their Obsidian vault, notes, tags,
  frontmatter, daily notes, backup, or sync. Route operations across MCP,
  Obsidian CLI/app actions, and git sync with safe defaults.
metadata:
  version: "2.2"
  author: bitbonsai
---

# Obsidian Skill

## Routing Policy

Use the backend that best matches user intent:

1. **MCP (default for vault data operations)**
   - Read/write/patch/search notes
   - Move/rename notes with `move_note`, then explicitly repair backlinks
   - Frontmatter and tag updates
   - Metadata and batch note operations

2. **Obsidian CLI/App context (only when app context is needed)**
   - Open a note in Obsidian from URI
   - Trigger app/plugin workflows that MCP cannot perform

3. **CLI git (sync/backup workflows)**
   - Initialize repo, configure remote, commit, pull, push
   - Periodic or manual vault backup/sync requests

When a request is ambiguous, pick MCP first unless the user explicitly asks for sync/backup/git/app behavior.

## Safe Note Rename Workflow

Use MCP `move_note` for every note move or rename, even when Obsidian is running. Do not invoke the Obsidian CLI `move` command automatically: delayed link rewrites can apply stale byte offsets to notes edited after the move began, silently corrupting unrelated content ([#176](https://github.com/bitbonsai/mcpvault/issues/176)). Reconsider CLI moves only after an upstream fix has been independently retested.

Backlink preservation is an explicit, verifiable second step:

1. Before moving, search for the old wikilink target using both its vault-relative path and filename without the extension. If Obsidian is running, its read-only `backlinks` command may supplement discovery, but it does not replace the MCP search.
2. Move the note with MCP `move_note`.
3. Read each referring note and patch only exact wikilink targets, including embeds and links with aliases or fragments. Preserve display text (`|alias`) and `#heading` / `#^block-id` suffixes while changing the target.
4. Search again for the old path and basename. Report any remaining references instead of claiming success.
5. `search_notes` returns at most 20 results. If a search reaches that cap, or the old basename is ambiguous, tell the user exhaustive backlink repair cannot be proven and ask before continuing with a broader scan.

Report the move and backlink repair separately: which note moved, how many referring notes changed, and any stale references that remain.

## Gotchas

1. **patch_note rejects multi-match by default.** With `replaceAll: false`, if `oldString` appears more than once the call fails and returns `matchCount`. Set `replaceAll: true` only when you mean it, or add surrounding context to make the match unique.

2. **patch_note matches inside frontmatter.** The replacement runs against the full file including the YAML block. A generic string like `title:` will match frontmatter fields. Include enough context to target the right occurrence.

3. **patch_note forbids empty strings.** Both `oldString` and `newString` must be non-empty and non-whitespace. To delete text, use `newString` with a single space or restructure the note with `write_note`.

4. **search_notes returns minified JSON.** Fields are abbreviated: `p` (path), `t` (title), `ex` (excerpt), `mc` (matchCount), `ln` (lineNumber), `uri` (obsidianUri). Hard cap of 20 results regardless of `limit`.

5. **search_notes multi-word queries score terms individually AND as a phrase.** Each term is OR-matched, so a document matching any term appears in results. The full phrase gets an additional scoring boost.

6. **write_note auto-creates directories.** Parent folders are created recursively. In `append`/`prepend` mode, if the note doesn't exist it's created. Frontmatter is merged (new keys override) in append/prepend; replaced entirely in overwrite.

7. **delete_note requires exact path confirmation.** `confirmPath` must be character-identical to `path`. No normalizat