obsidian

Obsidian スキル

ルーティングポリシー

ユーザーの意図に最も合ったバックエンドを使用します。

1. MCP（ボルトデータの操作ではデフォルト）

   • ノートの読み取り／書き込み／パッチ／検索
   • move_note でノートを移動／名前変更し、その後、バックリンクを明示的に修復
   • フロントマターとタグの更新
   • メタデータとノートの一括操作

2. Obsidian CLI／アプリのコンテキスト（アプリのコンテキストが必要な場合のみ）

   • URI から Obsidian でノートを開く
   • MCP では実行できないアプリ／プラグインのワークフローを起動する

3. CLI git（同期／バックアップのワークフロー）

   • リポジトリの初期化、リモートの設定、コミット、プル、プッシュ
   • 定期的または手動でのボルトのバックアップ／同期の依頼

依頼の内容が曖昧な場合、ユーザーが同期／バックアップ／git／アプリの操作を明示的に求めていない限り、まず MCP を選択します。

安全なノートの名前変更ワークフロー

Obsidian が起動している場合も含め、ノートを移動または名前変更するたびに MCP の move_note を使用します。Obsidian CLI の move コマンドを自動的に実行しないでください。リンクの書き換えが遅れて実行されると、移動の開始後に編集されたノートに古いバイトオフセットが適用され、無関係な内容が気付かれないまま破損するおそれがあります（#176）。上流の修正が独立して再テストされた後にのみ、CLI による移動を再検討してください。

バックリンクの保持は、明示的かつ検証可能な2つ目の手順です。

1. 移動前に、ボルトからの相対パスと、拡張子を除いたファイル名の両方を使って、古い wikilink のリンク先を検索します。Obsidian が起動している場合、読み取り専用の backlinks コマンドで検索を補完できますが、MCP による検索の代わりにはなりません。
2. MCP の move_note でノートを移動します。
3. 参照元の各ノートを読み込み、埋め込みやエイリアスまたはフラグメント付きのリンクを含め、完全一致する wikilink のリンク先のみをパッチします。リンク先を変更する際は、表示テキスト（|alias）と #heading ／ #^block-id の接尾辞を保持します。
4. 古いパスとベース名を再度検索します。残っている参照があれば、成功したと主張せずに報告します。
5. search_notes が返す結果は最大20件です。検索結果が上限に達した場合、または古いベース名が曖昧な場合は、バックリンクを漏れなく修復できたことを証明できないとユーザーに伝え、より広範なスキャンを続ける前に確認を求めます。

移動とバックリンクの修復は別々に報告します。移動したノート、変更した参照元ノートの数、残っている古い参照を伝えてください。

注意点

1. patch_note はデフォルトで複数一致を拒否します。 replaceAll: false の場合、oldString が複数回出現すると呼び出しは失敗し、matchCount が返されます。意図している場合に限り replaceAll: true を設定するか、前後の文脈を加えて一致箇所を一意にしてください。

2. patch_note はフロントマター内も検索します。 置換は YAML ブロックを含むファイル全体に対して実行されます。title: のような一般的な文字列はフロントマターのフィールドに一致します。対象の箇所を指定できるよう、十分な文脈を含めてください。

3. patch_note では空文字列を使用できません。 oldString と newString はどちらも空ではなく、空白文字のみでもない必要があります。テキストを削除するには、newString に半角スペースを 1 つ指定するか、write_note でノートを再構成してください。

4. search_notes は最小化された JSON を返します。 フィールド名は短縮されています。p（パス）、t（タイトル）、ex（抜粋）、mc（一致数）、ln（行番号）、uri（obsidianUri）です。limit の値にかかわらず、結果は最大 20 件です。

5. search_notes の複数語クエリは、各語とフレーズの両方でスコアを付けます。 各語は OR 条件で照合されるため、いずれかの語に一致するドキュメントが結果に表示されます。フレーズ全体には追加のスコアが付与されます。

6. write_note はディレクトリを自動作成します。 親フォルダーは再帰的に作成されます。append／prepend モードでは、ノートが存在しない場合に作成されます。フロントマターは append／prepend ではマージされ（新しいキーが優先）、overwrite では全体が置き換えられます。

7. delete_note ではパスの完全一致による確認が必要です。 confirmPath は path と文字単位で完全に一致する必要があります。正規化は行われず、末尾のスラッシュも許容されません。一致しない場合、success: false で暗黙的に失敗します。

8. move_file では二重の確認が必要です。 confirmOldPath と confirmNewPath は、対応するパスと完全に一致する必要があります。Markdown ファイルの名前変更には、テキストを考慮し確認が不要な move_note を使用してください。move_file はバイナリファイルの場合、またはバイナリセーフな移動が必要な場合にのみ使用してください。

9. manage_tags は 2 つのソースを読み取りますが、書き込み先は 1 つです。 list はフロントマターのタグとインラインの #hashtags を統合します。add／remove はフロントマターの tags 配列のみを変更します。インラインタグは変更されません。

10. read_multiple_notes は失敗を拒否しません。 内部で allSettled を使用します。失敗したファイルは err 配列に、成功したファイルは ok 配列に含まれます。必ず両方を確認してください。1 回の呼び出しで指定できるパスは最大 10 件です。

エラーからの復旧

エラー	次の手順
patch_note "Found N occurrences"	oldString に前後の行を加えて一致箇所を一意にするか、replaceAll: true を設定します
delete_note / move_file の確認不一致	read_note または list_directory でノートのパスを再確認してから、完全一致する文字列で再試行します
search_notes が 0 件を返す	フレーズではなく単一のキーワードを試すか、searchFrontmatter を切り替えるか、部分語句を使って検索範囲を広げます
read_multiple_notes の err が一部のみ	list_directory で失敗したパスを確認し、誤字や拡張子の欠落を修正して、失敗したものだけ再試行します

Git 同期モード

ユーザーが「sync」「backup」または「vault を git で保存」と依頼した場合は、次の動作で CLI git を使用します。

1. 変更を加える前に、事前確認を実行します：

   • git が利用可能であること
   • 現在のディレクトリが git リポジトリであること（または初期化を提案すること）
   • git config user.name と git config user.email が設定されていること
   • push／pull 同期用のリモートが少なくとも 1 つ存在すること

2. 事前確認が完了していない場合は、推奨されるデフォルトを添えて、対象を絞った質問を 1 つだけします。

   • 動作を大きく変える判断には askuserquestion を使用します。
   • 適切な例：
     • 「git リポジトリが見つかりません。この vault で初期化しますか？（推奨：はい）」
     • 「リモートが設定されていません。利用可能な場合は gh で GitHub リモートを設定しますか？それともリモート URL を指定しますか？（推奨：gh で設定）」
     • 「ローカルとリモートで履歴が分岐しています。今すぐ git pull --rebase を試しますか？（推奨：はい）」

3. 安全な同期手順（デフォルトでは force push を行いません）：

   • git add -A
   • git commit -m "vault sync: YYYY-MM-DD HH:mm"（変更がなければコミットをスキップ）
   • git pull --rebase
   • git push

4. gh は任意です：

   • 要求された場合に限り、リモートの初期設定（リポジトリの作成／origin の設定）に gh を使用します。
   • リモートの設定後、通常の同期に gh は必要ありません。

5. 競合が発生した場合は停止し、次に行うべきことを明確に伝えます。

   • マージの競合を黙って自動解決しないでください。
   • 何が失敗したのか、ユーザーが次に実行すべき内容を説明します。

Obsidian CLI モード

ユーザーからアプリのコンテキストを伴う操作（アクティブファイル、エディターで開く、テンプレートを使ったデイリーノート、バックリンク）を依頼された場合は、シェルコマンドから Obsidian CLI を直接使用します。

1. CLI を初めて使用する前に事前確認を実行します：

   • 次の候補のうち、最初に見つかったものを CLI バイナリとして解決します：

     優先度	macOS	Linux	Windows
     1	obsidian (PATH)	obsidian (PATH)	obsidian.exe または Obsidian.com (PATH)
     2	/Applications/Obsidian.app/Contents/MacOS/obsidian-cli	—	—
     3	/Applications/Obsidian.app/Contents/MacOS/Obsidian	—	—

     Obsidian 1.12.7+ のインストーラーには、専用の obsidian-cli バイナリが同梱されています（従来の Electron ベース CLI より約 10 倍高速で、1 回の呼び出しあたり約 25 ms 対約 250 ms です）。macOS では、1.12.7+ のインストーラーをインストールした後、設定 > 一般 > 詳細設定で CLI を無効にしてから再度有効にし、PATH 登録を更新します。これにより、古い ~/.zprofile の PATH エントリーが、obsidian-cli を指す /usr/local/bin/obsidian シンボリックリンクに置き換わります。

     Linux では、PATH 登録によって /usr/local/bin/obsidian（またはフォールバックとして ~/.local/bin/obsidian）にシンボリックリンクが作成されます。Windows では、インストーラーによって Obsidian.com ターミナルリダイレクターが Obsidian.exe と同じ場所に配置されます。

     注： 優先度テーブルと古い PATH の確認は、macOS でのみ検証されています。Linux と Windows でも 1.12.7+ のインストーラーに obsidian-cli が同梱される可能性がありますが、確認されていません。Issue または PR での貢献を歓迎します。

   • 古い PATH の確認（macOS）： 優先度 1 で PATH 上の obsidian が解決された場合、高速なバイナリを指しているか、低速な Electron ランチャーを指しているかを確認します：

     解決されたパス	意味	対応
     /usr/local/bin/obsidian → obsidian-cli	1.12.7 のシンボリックリンク登録	不要 — 高速なバイナリです
     /Applications/.../MacOS/obsidian	古い ~/.zprofile エントリー（1.12.7 より前の登録、または再登録していない 1.12.7 インストーラー）	バンドル内に obsidian-cli が存在するか確認します

     obsidian が MacOS ディレクトリに解決され（/usr/local/bin ではなく）、かつ /Applications/Obsidian.app/Contents/MacOS/obsidian-cli が存在する場合は、ユーザーに次のように伝えます： 「Obsidian 1.12.7+ はインストールされていますが、PATH はまだ低速な Electron バイナリを指しています。Obsidian で、設定 > 一般 > 詳細設定に移動し、CLI を無効にしてから再度有効にして、PATH 登録を更新してください。」 一致した優先度の候補をそのまま使用して続行します。これは案内であり、処理を妨げるものではありません。

   • Obsidian が実行中であることを確認します：pgrep -xiq obsidian（macOS/Linux）または tasklist /FI "IMAGENAME eq Obsidian.exe" /NH（Windows）

   • いずれかの確認に失敗した場合はユーザーに伝え、MCP ツールと obsidian:// URI にフォールバックします。

2. Vault の指定：obsidian vault="VaultName" <command>。OBSIDIAN_VAULT_NAME が設定されている場合は、その明示的な値を使用します。設定されていない場合は obsidian vaults を実行し、MCP の Vault パスを登録済み Vault と照合して、登録名を使用します。一意に一致するものがない場合は、ユーザーに確認します。フォルダーのベース名から登録名を推測してはいけません。

3. 主なコマンド：

   # Read the currently active file
   obsidian read
   
   # Read a specific file
   obsidian read file="My Note"
   
   # Open a file in Obsidian
   obsidian open path="Notes/example.md"
   
   # Open today's daily note
   obsidian daily
   
   # Append to daily note
   obsidian daily:append content="- [ ] New task"
   
   # Search (Obsidian's own search, different from MCP's BM25)
   obsidian search query="meeting notes" limit=10
   
   # List all tags with frequency
   obsidian tags sort=count counts
   
   # Get backlinks for a note
   obsidian backlinks file="My Note"
   
   # Find unresolved links
   obsidian unresolved
   

   obsidian move は使用せず、MCP の move_note と明示的なバックリンク修復による安全なノート名変更ワークフローに従います。

4. コマンドの全リファレンスは obsidian help を実行して確認します。CLI は Obsidian のリリースに伴って進化します。

5. CLI と MCP の使い分け：

   • 読み取り／書き込み／検索／タグ／フロントマター、およびすべてのノートの移動／名前変更には MCP を使用します（サンドボックス化され、検証済みで、ヘッドレス環境でも動作します）。
   • アクティブファイル、テンプレート展開を伴うデイリーノート、読み取り専用のバックリンク検出、エディターで開く操作、プラグインコマンドには CLI を使用します。
   • move_note の実行後は、安全なノート名変更ワークフローに従ってバックリンクを明示的に修復し、確認します。
   • 判断に迷う場合は MCP を優先します。

リソース

必要な場合にのみ読み込み、呼び出しごとに読み込む必要はありません。

• ツールのパターン - ツールのレスポンス形式やモードの詳細、move_note と move_file のどちらを選ぶかを確認する必要がある場合に読みます
• Obsidian の規約 - ノートの内容を作成・書き込みする場合（リンク構文、フロントマターのフィールド、デイリーノートの形式、テンプレート変数）に読みます
• Git Sync - git/gh を使ったバックアップ、同期、保管庫のワークフローをユーザーが求めた場合に読みます