obsidian-gh-knowledge

Obsidian GH Knowledge（CLI ファースト）

要約

• 目標： 環境に応じた、最も安全で最適な方法で Obsidian の保管庫をブートストラップして運用します。
• 実行順序： 0. リポジトリを確認後、ローカルクローンをブートストラップ -> 1. ローカルの Obsidian CLI -> 2. ローカルのフォールバック -> 3. GitHub API のフォールバック。
• エージェントのルール： エージェントは書き込み前に必ず読み取り、## TL;DR を含め、視覚的な説明には必ず Mermaid 図を使用します。
• プロジェクトのスコープ： 特定のプロジェクト（cmux、trends など）で作業する場合は、5️⃣-Projects/GitHub/<project>/ 以下にある、そのプロジェクトのフォルダー内にとどまってください。以下の「プロジェクトのスコープ（重要）」セクションを参照してください。
• ローカルラッパー： Obsidian CLI の操作と、この保管庫のプロジェクトルールおよび Git 同期を組み合わせた、再現性のある macOS でのローカルワークフローには scripts/local_obsidian_knowledge.py を使用してください。
• 生素材： 保管庫で raw/ が Git サブモジュールとしてマウントされている場合、整理済みのノート置き場ではなく、ソース入力の保存場所として扱ってください。
• 受信トレイの使い分け： raw/inbox は外部ソース素材のデフォルトの取り込み先です。0️⃣-Inbox は、すでに統合・整理され、まだ振り分けが必要なノートを置くための、整理済みのステージング領域です。
• 健全性のデフォルト： 保管庫が読みづらい、または信頼しにくいと感じた場合は、まず simplify-review を使用してください。保管庫全体の Obsidian 件数と、アクティブなスコープのグラフチェックおよび概要の可読性監査を照合します。
• Git 同期： ノートを更新する場合は、プッシュ前にプル／リベースすることを優先し、main への強制プッシュは絶対に行わないでください。タスク完了時には、その日のデイリーログに同期結果を記録してください。
• Git のブートストラップ： Obsidian CLI を利用できない場合でも、ローカルのブートストラップでは Git と raw/ サブモジュールを設定する必要があります。ベースラインではフックを使用せず、ブートストラップ中に古い core.hooksPath 設定を削除してください。

実行モードのフローチャート

graph TB
    A[Start Vault Operation] --> B{Local vault exists}
    B -- Yes --> C{Obsidian CLI ready}
    B -- No --> D{Confirmed vault repo URL}
    D -- Yes --> E[Clone vault into Documents]
    D -- No --> F[Use GitHub mode]
    E --> C
    C -- Yes --> G[Use local CLI mode]
    C -- No --> H[Use local git fallback]
    G --> I[Run operation]
    H --> I
    F --> I

このスキルは、Obsidian の保管庫を安全かつ一貫してブートストラップし、管理するために使用します。

取り込み先の使い分け（重要）

2 つの受信トレイは、意味を厳密に分けてください。

• raw/inbox：クリップした記事、コピーした投稿、文字起こし、インポートした Markdown、その他の保存するソース素材。
• 0️⃣-Inbox：すでに統合・整理、プロジェクトの枠組みの設定、または構造化された文書作成が済んでいるものの、まだ振り分けが必要なノート。

判断ルール：

• ソース素材自体を保存したい場合は、capture-raw を使用して raw/inbox に取り込みます。
• すでに推論や統合・整理を反映したノートが必要な場合は、capture を使用して 0️⃣-Inbox に取り込むか、最終的なプロジェクトフォルダーに直接書き込みます。
• 0️⃣-Inbox を生素材の投げ込み先として使用しないでください。
• 整理済みのノートを先に検索し、その後 raw/ を検索してください。

信頼できる情報源

• 主な最新ドキュメント：Context7 Obsidian CLI インデックス（/websites/help_obsidian_md_cli）
• CLI の公式ドキュメント：https://help.obsidian.md/cli/index
• CLI を紹介した一般公開のリリースノート：https://obsidian.md/changelog/2026-02-27-desktop-v1.12.4/
• 上流の再利用可能なスキルセット：https://github.com/kepano/obsidian-skills

注：CLI ドキュメントの一部には、まだ早期アクセスに関する記述が含まれている場合があります。公開チェンジログ（2026 年 2 月 27 日）をリリースの基準として扱ってください。

推奨するスキルの組み合わせ

用途に応じて、汎用の上流スキルと、このリポジトリ固有のスキルを使い分けてください。

• kepano/obsidian-skills/skills/obsidian-cli：標準的なコマンド構文と、現在の CLI 機能の範囲。
• kepano/obsidian-skills/skills/obsidian-markdown：Obsidian 向けの汎用 Markdown 作成ルール。
• kepano/obsidian-skills/skills/obsidian-bases：.base ダッシュボードと構造化されたナレッジビュー。
• このリポジトリの obsidian-gh-knowledge：ローカル保管庫のブートストラップ、プロジェクトのスコープ、絵文字フォルダーのガードレール、Git 同期、GitHub のフォールバック。

ローカルヘルパースクリプト scripts/local_obsidian_knowledge.py は、上流の汎用 CLI パターンと、この保管庫固有の慣習をつなぐものです。

実行モード（厳密な順序）

0. ローカルボルトをブートストラップする
   • ローカルボルトが見つからず、ユーザーがボルトのリポジトリ URL を確認した場合に使用します。
   • 現在のユーザーの ~/Documents/<repo-name> へのクローンを優先し、その後 local_vault_path を設定に書き込みます。
1. ローカル Obsidian CLI モード（ブートストラップ後に優先）
   • ローカルボルトが存在し、obsidian CLI が利用可能で有効な場合に使用します。
2. ローカルファイルシステム／git フォールバック
   • ローカルボルトは存在するものの、CLI が有効でない場合に使用します。
3. GitHub モードのフォールバック
   • ローカルボルトを利用できない場合、ブートストラップが確認されていない場合、またはローカルアクセスが明示的に無効化されている場合に使用します。

この順序は、デスクトップ、サーバー、サンドボックス環境間の互換性を確保するためのものです。

モード選択（ローカルまたは GitHub）

1. VAULT_DIR を解決します。
   • ~/.config/obsidian-gh-knowledge/config.json に local_vault_path がある場合は、それを使用します。
   • それ以外の場合は ~/Documents/obsidian_vault/ を使用します。
2. VAULT_DIR が存在せず、ユーザーがボルトのリポジトリ URL を確認している場合は、ブートストラップスクリプトを実行してから VAULT_DIR を再度解決します。
3. VAULT_DIR が存在し、prefer_local が false でない場合は、ローカルモードを使用します。
4. ローカルモードでは、次の条件を満たす場合に限り、公式 Obsidian CLI を優先します。
   • command -v obsidian が成功する
   • obsidian help が成功する（CLI が有効で、アプリとの接続が機能している）
5. CLI の確認に失敗した場合は、ローカルファイルシステム／git モードにフォールバックします。
6. ローカルモードを利用できない場合は、GitHub モードを使用します。

スクリプトパスヘルパー

リポジトリ内とユーザースキル内の両方のレイアウトで、バンドルされたスクリプトを見つけるには、1 つのヘルパーを使用します。

resolve_obsidian_gh_script() {
  local name="$1"
  local path
  for path in \
    "skills/obsidian-gh-knowledge/scripts/$name" \
    "agent-skills/skills/obsidian-gh-knowledge/scripts/$name" \
    "scripts/$name" \
    "$HOME/.agents/skills/obsidian-gh-knowledge/scripts/$name"
  do
    if [ -f "$path" ]; then
      printf '%s\n' "$path"
      return 0
    fi
  done
  echo "Could not find obsidian-gh-knowledge script: $name" >&2
  return 1
}

初回のワークスペースのブートストラップ

新しいワークスペースで、ボルトがまだローカルにチェックアウトされていない場合は、このワークフローを使用します。

ルール：

• ボルトのリポジトリを推測しないでください。まず、正確な GitHub リポジトリ URL をユーザーに確認してください。
• ユーザーが https://github.com/karlorz/obsidian_vault のようなリポジトリを確認した後は、GitHub のみのモードよりもローカルクローンを優先します。
• デフォルトの保存先は ~/Documents/<repo-name> です。上記の例では、~/Documents/obsidian_vault になります。
• ~ はユーザーごとに異なります。現在のユーザーが root の場合、デフォルトの保存先は /root/Documents/<repo-name> になります。
• --vault-dir は、ユーザーが別の保存先を明示的に希望する場合に限り使用します。

確認後に実行します。

INIT_SCRIPT_PATH="$(resolve_obsidian_gh_script init_local_vault.py)"

python3 "$INIT_SCRIPT_PATH" \
  --repo-url "https://github.com/karlorz/obsidian_vault" \
  --repo-key personal

ブートストラップスクリプトの動作：

• ユーザーが --vault-dir を指定しない限り、確認済みのボルトリポジトリを ~/Documents/<repo-name> にクローンします。
• 同じリポジトリのクローンがすでに存在する場合は、そのディレクトリを再利用します。
• --raw-submodule-url と --init-raw-submodule が指定されている場合、raw/ などの素材用サブモジュールを任意で初期化できます。
• Obsidian CLI を必要とせずに、ローカル Git のブートストラップを設定します。
  • extensions.worktreeConfig=true を有効にします
  • 共有およびワークツリー固有の Git 設定から、古い core.hooksPath 設定を消去します
  • ワークツリー固有の push.recurseSubmodules=on-demand を設定します
  • 設定済みの raw/ サブモジュールが存在する場合は初期化します
  • 安全に行える場合は、raw/ を設定済みのブランチと上流ブランチに関連付けます
• ~/.config/obsidian-gh-knowledge/config.json を更新します。
  • local_vault_path を設定します
  • prefer_local を true に設定します
  • 現在設定されていない場合は default_repo を設定します
  • --repo-key が指定されている場合は repos.<key> を追加します
  • 現在設定されていない場合は vault_name を設定します
  • raw サブモジュールのブートストラップを使用した場合は、raw_submodule_path と raw_submodule_url を設定します

任意の raw サブモジュールのブートストラップ：

python3 "$INIT_SCRIPT_PATH" \
  --repo-url "https://github.com/karlorz/obsidian_vault" \
  --repo-key personal \
  --raw-submodule-url "https://github.com/karlorz/obsidian_vault_raw.git" \
  --init-raw-submodule

ブートストラップ後は、モード選択を再実行し、新しい local_vault_path からローカル CLI またはローカル git フォールバックを優先します。

注意：

• このブートストラップ方法は、obsidian がインストールされていないヘッドレス環境またはリモート環境でも機能するように設計されています。
• Obsidian Git プラグインの設定は、デスクトップアプリ内で長期的な同期レイヤーとして機能します。ブートストラップでは Git とサブモジュールの状態のみを準備します。

ガードレール（パスの誤りを防ぐ）

• パスの確認時にエラーを抑制しないでください（2>/dev/null は使わないでください）。存在しないパスが明らかになるようにしてください。
• ローカルの vault が「見つからない」場合は、ブートストラップと GitHub フォールバックのどちらにするかを決める前に、診断情報として pwd、echo "$HOME"、ls -la "$(dirname "$VAULT_DIR")" を表示してください。
• 絵文字を含むフォルダー名を手入力しないでください。必ず ls／list を実行し、正確なパスをコピーしてください。
• この vault では 5️⃣-Projects（スペースなし）のような名前を使います。5️⃣ -Projects ではローカルの ls と GitHub の読み取りに失敗します。
• read が「File not found」で失敗した場合は、推測せず、直ちに親フォルダーを list するか、ファイル名を search してください。
• 絵文字を含むフォルダー名をプログラムで取得する必要がある場合：ls -1 "$VAULT_DIR" | rg -m1 "Projects$"（この vault では 5️⃣-Projects が返されます）。
• ユーザーが vault リポジトリの URL を確認するまでは、リポジトリをクローンしたり、local_vault_path を上書きしたりしないでください。

プロジェクトのスコープ設定（重要）

警告

よくある間違い エージェントは、間違ったプロジェクトフォルダーに移動することがよくあります（例：cmux で作業しているのに trends/ に移動する）。これはコンテキストを浪費し、ユーザーを混乱させます。

プロジェクトを対象とする操作のルール：

1. vault に対する操作を行う前に、まず現在のプロジェクトコンテキストを確認してください。

   • 現在の作業ディレクトリを確認します（例：/root/workspace の場合、プロジェクトを特定するために CLAUDE.md または package.json を探します）。
   • 会話の中でプロジェクトについて言及されているか確認します。
   • 曖昧な場合は、どのプロジェクトを指しているのかユーザーに尋ねてください。

2. すべての操作（読み取りと書き込み）を、正しいプロジェクトフォルダーに限定してください。

   • プロジェクトフォルダーは 5️⃣-Projects/GitHub/<project>/ の下にあります。
   • 例：cmux プロジェクト → 5️⃣-Projects/GitHub/cmux/
   • 例：trends プロジェクト → 5️⃣-Projects/GitHub/trends/

3. ほかの読み取りや書き込みを行う前に、必ず <project>/_Overview.md を読み、正しい場所であることを確認してください。

4. ユーザーから明示的な依頼がない限り、プロジェクトの境界を越えないでください。

   • cmux で作業している場合は、trends/ フォルダーを読み書きしないでください。
   • cmux のコンテキストでユーザーが「ロードマップ」を尋ねた場合は、trends/trends-dev-roadmap.md ではなく、cmux/cmux-agent-dev-roadmap.md を確認してください。

5. プロジェクトの検出ヒューリスティック（以下の順）：

   # 1. Check if current workspace has project identifier
   if [ -f "CLAUDE.md" ]; then
     PROJECT=$(grep -m1 "project.*cmux\|project.*trends" CLAUDE.md | grep -oE "cmux|trends" | head -1)
   fi
   
   # 2. Check package.json name field
   if [ -z "$PROJECT" ] && [ -f "package.json" ]; then
     PROJECT=$(jq -r '.name // empty' package.json 2>/dev/null | grep -oE "cmux|trends" | head -1)
   fi
   
   # 3. Check git remote
   if [ -z "$PROJECT" ]; then
     PROJECT=$(git remote get-url origin 2>/dev/null | grep -oE "cmux|trends" | head -1)
   fi
   

6. プロジェクトフォルダーを一覧表示する場合は、常に利用可能なフォルダーを表示してください：

   ls "$VAULT_DIR/5️⃣-Projects/GitHub/"
   # Output: cmux  data-labeling  openclaw  trends
   

簡単な確認：

# Local vault path
python3 - <<'PY'
import json, os
p = os.path.expanduser('~/.config/obsidian-gh-knowledge/config.json')
if os.path.exists(p):
    c = json.load(open(p))
    print(os.path.expanduser(c.get('local_vault_path', '~/Documents/obsidian_vault')))
else:
    print(os.path.expanduser('~/Documents/obsidian_vault'))
PY

# CLI availability
command -v obsidian
obsidian help

obsidian help の出力に Command line interface is not enabled と表示された場合は、Obsidian の設定で有効にするまで、ローカルファイルシステムへのフォールバックを使用してください。

環境との互換性

• Obsidian アプリを実行中の macOS／Windows デスクトップ：ローカル Obsidian CLI モードを使用してください。
• Obsidian GUI を利用できる Linux デスクトップ：CLI が動作する場合があります。上記と同じ確認を行ってください。
• GUI アプリのセッションがないヘッドレス Linux／コンテナー／サンドボックス：Obsidian CLI は利用できないものとして扱い、ローカルファイルシステムまたは GitHub モードに直接進んでください。
• 多くのサンドボックスでは、~/.config/obsidian-gh-knowledge/config.json と ~/Documents/obsidian_vault はデフォルトで存在しません。確認済みのリポジトリ URL を使ったブートストラップ、または明示的な --repo の使用を想定してください。

ヘッドレス環境では、CLI を待って実行を止めないでください。

ローカル Obsidian CLI モード（推奨）

要件

• Obsidian デスクトップ 1.12+。
• アプリの設定で CLI が有効になっていること：Settings -> General -> Advanced -> Command line interface。
• Obsidian アプリを起動できること。アプリがまだ実行されていない場合、最初の CLI コマンドで起動することがあります。
• macOS では、PATH に /Applications/Obsidian.app/Contents/MacOS が含まれていることを確認してください。
• CLI コマンドが失敗し、標準エラー出力に Unable to find helper app または Command line interface is not enabled と表示された場合は、設定で CLI を再度有効にし、ターミナルを再起動してください。コマンドが成功し、ヘルパーに関する警告だけが出力された場合は、その警告を無視して続行してください。

vault とファイルの指定

• 現在のディレクトリが vault の場合、コマンドはその vault を対象にします。
• それ以外の場合は、最初のパラメーターとして vault=<name> を使用してください。
• wikilink 形式で解決するには file=<name> を、正確なパスを指定するには path=<exact/path.md> を使用してください。

例：

# Prefer running inside vault root
cd "$VAULT_DIR"

# Or target by vault name explicitly
obsidian vault="My Vault" search query="test"

# Exact file targeting
obsidian read path="5️⃣-Projects/GitHub/cmux/_Overview.md"

基本的なコマンドパターン

# Search and read
obsidian search query="MOC" path="5️⃣-Projects/" format=json
obsidian read path="5️⃣-Projects/GitHub/cmux/_Overview.md"

# Create/update content
obsidian create path="2️⃣-Drafts/new-note.md" content="# Title\n\n## TL;DR\n"
obsidian create path="2️⃣-Drafts/new-note.md" content="# Title\n\n## TL;DR\n- [ ] Follow up" overwrite
obsidian append path="2️⃣-Drafts/new-note.md" content="\n- [ ] Follow up"

# Move/rename and delete
obsidian move path="0️⃣-Inbox/note.md" to="5️⃣-Projects/GitHub/cmux/note.md"
obsidian delete path="2️⃣-Drafts/tmp-note.md"

# Tasks, tags, properties, templates, daily note
obsidian tasks path="5️⃣-Projects/GitHub/cmux/_Overview.md" todo format=json
obsidian tags counts
obsidian properties path="5️⃣-Projects/GitHub/cmux/_Overview.md"
obsidian templates
obsidian template:read name="github-project-template"
obsidian daily
obsidian daily:append content="- [ ] Review inbox"

高レベルのローカルラッパー

一般的な macOS のワークフローでは、コマンドを手作業で組み立てるのではなく、リポジトリ固有のヘルパーを優先してください。

LOCAL_WRAPPER="$(resolve_obsidian_gh_script local_obsidian_knowledge.py)"

python3 "$LOCAL_WRAPPER" doctor
python3 "$LOCAL_WRAPPER" dashboard
python3 "$LOCAL_WRAPPER" review
python3 "$LOCAL_WRAPPER" simplify-review
python3 "$LOCAL_WRAPPER" audit
python3 "$LOCAL_WRAPPER" fix-tldr --dry-run
python3 "$LOCAL_WRAPPER" structure-report --dry-run
python3 "$LOCAL_WRAPPER" structure-fix --dry-run
python3 "$LOCAL_WRAPPER" archive-fix --dry-run
python3 "$LOCAL_WRAPPER" capture-raw "Clipped article" --source "https://example.com/post"
python3 "$LOCAL_WRAPPER" capture "Curated summary note"
python3 "$LOCAL_WRAPPER" project-note cmux "Feature review"
python3 "$LOCAL_WRAPPER" organize "0️⃣-Inbox/feature-review.md" cmux
python3 "$LOCAL_WRAPPER" sync --message "Update vault notes"

--vault-dir はグローバルオプションです。必要な場合はサブコマンドの前に指定してください。例：python3 "$LOCAL_WRAPPER" --vault-dir "$VAULT_DIR" doctor。

ラッパーの役割：

• 設定からローカルのボルトパスを解決します。
• 設定されている場合、doctor で raw/ サブモジュールの状態を報告します。
• worktree 固有の push.recurseSubmodules など、ローカルの Git／ブートストラップの状態を報告します。
• 利用可能な場合は、公式の obsidian CLI を検証します。
• CLI が見つからなくても処理を失敗させません。doctor は、リモートまたはヘッドレスのワークスペース向けに、ローカルの Git／ブートストラップの準備状況を引き続き報告します。
• ボルトの健全性指標、タスク数、最近のファイル、未解決リンクのサンプル、raw とキュレーション済みの取り込み件数を明示したワンクリックの review サマリーを実行します。
• dashboard と review の孤立／行き止まりの件数は、Obsidian のボルト全体に関する指標として扱います。アクティブなノートの正確な整理対象範囲を示すものではありません。
• review、audit、アクティブ範囲の構造分析、概要の可読性チェック、ベース名／エイリアスの重複検出を組み合わせた simplify-review を実行し、単一のレポートノートにまとめます。
• 必須フォルダー、プロジェクトの _Overview.md の網羅状況、## TL;DR の配置、大きすぎる MOC、古い Structure Cleanup Inbox の未処理項目、YAML フロントマターの解析を対象とする、より厳格な audit を実行します。
• ## TL;DR がないノートに、プレースホルダーの ## TL;DR セクションを一括挿入できます。
• 不安定な CLI のライブリスト出力に依存せず、アクティブ範囲の孤立ノートと行き止まりノートを対象に、ローカルのグラフベースの構造整理レポートを生成できます。
• 行き止まりノートを最も近い _Overview.md にリンクし、孤立ノートをプロジェクト MOC 内の自動生成された整理セクションに追加することで、信頼度の高い構造修正を適用できます。
• 不足している _Archive-Index.md ノートを作成し、アーカイブされたノートへのバックリンクを追加できます。これにより、アクティブな MOC に不要なノートを混在させずに、アーカイブフォルダーをナビゲートしやすく保てます。
• raw/ サブツリーは、可読性監査と TL;DR 監査の対象外とします。raw 素材はキュレーション済みのノートではなく、ソース入力だからです。
• 外部ソース素材のデフォルトの取り込み先として raw/inbox を、キュレーション済みの一時置き場として 0️⃣-Inbox を扱います。
• プロジェクトのノートを作成または整理する前に、_Overview.md を読みます。
• ノートの移動には obsidian move を使用し、シェルで直接名前を変更するのではなく、Obsidian 内で移動します。
• 必要に応じて、最後に local_vault_git_sync.py を実行します。
• デフォルトでは、サブモジュールが変更済み、または初期化されていない場合に同期をブロックします。その意図がある場合に限り、--allow-dirty-submodules を使用してください。

ローカル書き込みワークフロー

1. 書き込む前に読みます（obsidian read ...）。
2. 大規模な編集では、まず下書きノートに書き込み、その後、意図を持って統合します。
3. リモートとの同期を保ちます。pull/rebase、commit、push の順に実行してください（force-push はしません）。
4. ノートの同期が正常に完了した後、ボルトのワークフローまたはタスクの状況で必要な場合は、/root/lifecycle/memory/daily/<YYYY-MM-DD>.md に短い実行サマリーを追記します。

推奨（1 コマンド）：

LOCAL_SYNC_SCRIPT="$(resolve_obsidian_gh_script local_vault_git_sync.py)"

python3 "$LOCAL_SYNC_SCRIPT" \
  --vault-dir "$VAULT_DIR" \
  --message "Update vault notes"

手動でのワークフロー：

cd "$VAULT_DIR"
# If raw/ has changes: commit+push inside raw/ first, then return to parent.
git -C raw status --porcelain=v1   # use `git -C`, not `cd raw` — Bash CWD persists
# git -C raw add -A && git -C raw commit -m "..." && git -C raw push
git pull --rebase --autostash
git status --porcelain=v1
git add -A                          # includes bumped raw/ submodule pointer
git commit -m "Update vault notes"
git pull --rebase
git push

リモート側が進んだために git push が拒否された場合は、新しい origin/main の先端に対して fetch/rebase を行い、push を再試行してください。force-push で解決してはいけません。

ローカルのファイルシステム／Git へのフォールバック（CLI を利用できない場合）

ローカル CLI を使用できない場合に限り使用してください。

VAULT_DIR="$HOME/Documents/obsidian_vault"

ls -la "$VAULT_DIR"
rg -n "keyword" "$VAULT_DIR"
sed -n '1,160p' "$VAULT_DIR/5️⃣-Projects/GitHub/cmux/_Overview.md"

編集では、ローカル CLI モードと同じ同期ワークフロー（commit + pull/rebase + push）を使用してください。

GitHub モードへのフォールバック

ローカルのボルトを利用できない場合、または prefer_local が明示的に false の場合に使用してください。

GitHub の読み取りプロトコル（「File not found」を防ぎます）：

1. 親フォルダーを list して、正確なパスをコピーします
2. ファイル名／キーワードが不明な場合は search します
3. 返された正確なパスを使って read します

リポジトリ解決ポリシー

次の順序でリポジトリを解決します。

1. 指定されている場合は --repo <owner/repo>。
2. --repo <key>（/ を含まない場合）は、設定内の repos.<key> から解決します。
3. 設定内の default_repo。
4. いずれも利用できない場合は、停止してリポジトリまたは設定を確認してください。

リポジトリ名を推測してはいけません。

要件

• GitHub CLI がインストールされていること：gh
• 認証済みであること：gh auth status
• 読み取り／書き込みの前にリポジトリへのアクセスを確認すること：
  • gh repo view <owner/repo> >/dev/null
  • 失敗した場合は停止し、現在のアカウント／チームがアクセスできるリポジトリを依頼してください。

コマンド

SCRIPT_PATH="$(resolve_obsidian_gh_script github_knowledge_skill.py)"

python3 "$SCRIPT_PATH" \
  --repo <owner/repo> <command> [args]

利用可能なコマンド：

• list --path <path>
• read <file_path>
• search <query>
• move <src> <dest> --branch <branch_name> --message <commit_msg>
• copy <src> <dest> --branch <branch_name> --message <commit_msg>
• write <file_path> --stdin|--from-file <path> --branch <branch_name> --message <commit_msg>

ヘッドレス Linux のスモークチェック

サンドボックスで大規模な作業を始める前に、次を実行してください。

command -v obsidian || true
gh auth status
python3 "$SCRIPT_PATH" --repo <owner/repo> list --path ""
python3 "$SCRIPT_PATH" --repo <owner/repo> read "README.md"
python3 "$SCRIPT_PATH" --repo <owner/repo> search "filename:_Overview.md"

最近の検証で確認された動作：

• ヘッドレス Linux では、obsidian を利用できないことがよくあります。
• --repo を明示し、gh にアクセス権がある場合は、GitHub モードが動作します。
• 絵文字を含むパスは、引用符で囲むとサポートされます：
  • python3 "$SCRIPT_PATH" --repo <owner/repo> list --path "0️⃣-Inbox"

安全上のルール（重要）

1. main への強制プッシュは絶対に行わないでください。
2. GitHub モードでは、必ずフィーチャーブランチで書き込みを行ってください。
3. GitHub モードでは、マージ前に必ずレビュー用の PR を作成してください。
4. 書き込む前に読み取ってください。
5. コミットは小さく、対象を絞ってください。
6. 利用可能な場合は、ローカルの Vault 操作を優先してください。

実用的なヒント（パスと絵文字）

• 特に絵文字を含むフォルダーでは、パスを必ず引用符で囲んでください（"..."）。
• パスを再入力するのではなく、コマンド出力から正確なパスをコピーすることを推奨します。
• GitHub モードで 404／パスエラーが発生した場合は、まず list で確認してください。
• リポジトリのルートに対する list も失敗する場合は、パスの入力ミスだけでなく、リポジトリの権限またはアカウント／チームのコンテキストの誤りとして扱ってください。

Obsidian ノートの作成ルール

リポジトリレベルの AGENTS.md がある場合は、まずそれに従ってください。

エージェント向け Markdown ルール

• 必須： 人がすばやく確認できるよう、冒頭付近に短い ## TL;DR を必ず含めてください。
• 必須： アーキテクチャ、ワークフロー、複雑な概念を視覚的に説明するため、Mermaid 図（graph TB または sequenceDiagram）を必ず使用してください。
• 内部ノートには Obsidian のウィキリンク（[[note-title]]）を使用してください。
• 名前変更／移動が依頼されていない限り、見出しは変更しないでください。
• 必要に応じて、メタデータには YAML フロントマターを使用してください。

Mermaid（Obsidian 互換性）

• graph TB／sequenceDiagram を推奨します。
• subgraph "Title" を使用してください（subgraph ID[Label] は避けてください）。
• ラベル内で \n を避け、<br/> または 1 行のラベルを使用してください。
• ノード ID は ASCII でシンプルなものにしてください（CMUX_DB、OC_GW）。

プロジェクトフォルダーの規約

5️⃣-Projects/ 内の各プロジェクトフォルダーには、MOC として _Overview.md を含める必要があります。

プロジェクトフォルダーを作成する場合：

1. 適切なカテゴリ（GitHub、Infrastructure、Research）にフォルダーを作成します。
2. まず _Overview.md を作成します。
3. クイックナビゲーションとドキュメントのインデックスを含めます。
4. 関連するノートを _Overview.md からリンクします。

テンプレート

GitHub プロジェクトのノートには、100-Templates/github-project-template.md を使用してください。

GitHub モードの例：

python3 ~/.agents/skills/obsidian-gh-knowledge/scripts/github_knowledge_skill.py \
  --repo <owner/repo> read "100-Templates/github-project-template.md"

設定ファイル

初回実行時には、scripts/init_local_vault.py を使って ~/.config/obsidian-gh-knowledge/config.json を作成することを推奨します。リポジトリまたは Vault の名前を調整する必要がある場合に限り、ファイルを手動で編集してください。

設定の形式：

{
  "default_repo": "<owner>/<vault-repo>",
  "repos": {
    "personal": "<owner>/<vault-repo>",
    "work": "<org>/<work-vault-repo>"
  },
  "local_vault_path": "~/Documents/obsidian_vault",
  "prefer_local": true,
  "vault_name": "My Vault"
}

vault_name は省略可能です。Vault ディレクトリの外で CLI コマンドを実行する場合に使用してください。

ワークフローのリファレンス

具体的なノート整理のワークフローパターンについては、references/obsidian-organizer.md を参照してください。

関連項目

• [[vault-operations-index|Vault 操作インデックス]]