mcpField
B
building-github-index

building-github-index

github.com/oaustegardエージェントワークフロー15746 回インストール1 日前に更新
リポジトリ

building-github-index について

Claudeのプロジェクトナレッジから検索するため、GitHubリポジトリのMarkdownインデックスを作成するスキルです。ドキュメントとコードに対応し、メタデータ、見出し、ノートブック、シンボル、ファイルパスから説明を作成します。

主な機能

  1. 01単一または複数リポジトリのインデックス作成
  2. 02リポジトリ内容からの説明抽出
  3. 03tree-sitterによるコードシンボル抽出
  4. 04ファイルパターンによる対象指定
  5. 05簡潔なプロジェクトナレッジ用インデックス

活用シーン

  1. 01リポジトリのドキュメント検索用インデックス作成
  2. 02公開関数やクラスに基づくコードの索引付け
  3. 03複数リポジトリのインデックス統合

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/oaustegard/claude-skills --skill building-github-index

インストール後、Claude Code で/building-github-indexを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

CHANGELOG.md
README.md
scripts/
github_index.py
pk_index.py

詳細

GitHub インデックスの作成

Claude プロジェクトのナレッジ向けに最適化された、GitHub リポジトリの Markdown インデックスを作成します。インデックスを使うと、効果的に一致するようセマンティックな説明を付けて、GitHub API 経由で情報を取得できます。

クイックスタート

# Documentation repos (markdown/notebooks)
python scripts/github_index.py owner/repo -o index.md

# Code repos (extract symbols via tree-sitter)
python scripts/github_index.py owner/repo --code-symbols -o index.md

# Multiple repos combined
python scripts/github_index.py owner/repo1 owner/repo2 -o combined.md

スクリプトのオプション

フラグ説明
-o, --output出力ファイル（デフォルト：github_index.md）
--tokenGitHub PAT。GITHUB_TOKEN 環境変数も読み取ります
--include-patterns一致する glob のみをインデックス化します："docs/" "src/"
--exclude-patterns一致する glob をスキップします："test/**"
--max-filesリポジトリごとのファイル数の上限（デフォルト：200）
--skip-fetchツリーのみを対象とし、コンテンツは取得しません（高速、ファイル名のみの説明）
--code-symbolsコードファイルを含め、tree-sitter 経由で関数名／クラス名を抽出します

説明の抽出優先順位

  1. YAML フロントマター - title: と description: フィールド
  2. Markdown 見出し - 最初の h1/h2 をタイトル、以降をトピックとして使用します
  3. ノートブックセル - 最初の Markdown セルの見出し
  4. コードシンボル - 公開関数名／クラス名（--code-symbols を指定）
  5. パスからの推定 - ファイル名を単語に変換します（フォールバック）

説明を抽出できない場合

一部のリポジトリには、スタブファイル（外部ドキュメントへのリンク、空の README）が含まれています。このような場合は、次の方法をおすすめします。

手動でのキュレーションをおすすめします。 ツリー出力とドメイン知識を活用してください。

# Get tree structure only (fast)
python scripts/github_index.py owner/repo --skip-fetch -o skeleton.md
# Then manually enhance descriptions based on domain knowledge

アプリが組み込まれたコード中心のリポジトリの場合：

  • ディレクトリ名は目的を表します：acc_wav_gen → 「ACC 波形生成」
  • 周辺機器の略称は機能に対応します：AFEC=ADC、MCAN=CAN、TWIHS=I2C
  • 動作モード：blocking、interrupt、dma、polled

出力形式

# {Repo} - Content Index

**Repository:** {url}
**Branch:** `{branch}`

## Retrieval Method
{API curl commands}

---

## {Category}

| Description | Path |
|-------------|------|
| {What this covers} | `{path/file.md}` |

関連性のマッチングを重視して説明列を先に置き、取得キーとなるパスを後に続けます。

API アクセス

ファイルの一覧表示：

curl -sL "https://api.github.com/repos/OWNER/REPO/git/trees/BRANCH?recursive=1"

コンテンツの取得：

curl -s "https://api.github.com/repos/OWNER/REPO/contents/PATH?ref=BRANCH" \
  -H "Accept: application/vnd.github+json" | \
  python3 -c "import sys,json,base64; print(base64.b64decode(json.load(sys.stdin)['content']).decode())"

ネットワーク

どちらのスクリプトもリポジトリの tarball をダウンロードし（HTTP リクエストは 1 回のみで、ファイルごとのレート制限はありません）、その後、ファイルをローカルで処理します。許可リスト：api.github.com（tarball はこのエンドポイント経由でリダイレクトされます）

関連スキル

  • accessing-github-repos - プライベートリポジトリ、PAT の設定、tarball のダウンロード
  • tree-sitting - 詳細なコード構造（メソッド、インポート、行番号）

圧縮形式（pk_index.py）

プロジェクトのナレッジで使用できるトークン数が限られている場合は、圧縮スクリプトを使用してください。

python scripts/pk_index.py owner/repo -o repo_pk.md

出力サイズを約 80% 削減できます。

  • ファイルごとに 1 行：path — 説明
  • シンボルのみ（シグネチャなし）
  • カテゴリごとに最大 15 ファイル
  • 取得手順のセクションなし

複数のリポジトリインデックスをプロジェクトのナレッジに追加する場合に最適です。

コメント

Markdown 対応