説明

SEART CSVエクスポート（リポジトリリスト）を取り込み、各リポジトリをスキャンして SKILL.md ファイルの有無を確認し、結果を1つの出力CSVにエクスポートして後続処理に渡すことで、SKILL.md ファイルを含むGitHubリポジトリを発見・選別します。

このスキルは、AIコーディングエージェントや自動化スクリプトが、レート制限に対応したスキャンと再開可能な実行により、大規模なリポジトリセットに対して反復可能で読み取り専用のマイニングを実行できるように設計されています。

このスキルを使用するタイミング

このスキルは以下の場合に使用します：

SEARTで生成された、GitHubリポジトリ識別子を含むCSVファイルのフォルダがある場合。
SKILL.md（デフォルトでは正確な名前）を含むリポジトリを見つける必要がある場合。
後続処理（ダウンロード、解析、インデックス作成）のために選別リストCSVをエクスポートする必要がある場合。

コンテンツ抽出、ライセンス準拠レビュー、脆弱性スキャン、リポジトリの変更にはこのスキルを使用しないでください。

入力

必須

SEART CSVフォルダ
- 1つ以上の .csv ファイルを含むディレクトリへのパス。
- 各CSVには、GitHubリポジトリ識別子を owner/repo の形式で再構築するための十分な情報が含まれている必要があります。
出力CSVパス
- スキャン結果を書き込むパス。

オプション設定

match_name: デフォルト SKILL.md
case_sensitive: デフォルト true
search_paths: デフォルト ["/SKILL.md"]
- 必要に応じて、一般的な場所を含めるようにこのリストを拡張できます。
include_negative_results: デフォルト true
- false の場合、マッチが見つかったリポジトリのみを出力します。
max_repos: デフォルト 0（無制限）
resume: デフォルト true
- 以前の出力ファイルから続行できます。
concurrency: デフォルト 8
min_stars: デフォルト 0
allow_forks: デフォルト true
allow_archived: デフォルト true

期待されるCSVスキーマ（SEART）

SEARTのエクスポート形式はさまざまです。このスキルは複数のパターンをサポートします。リポジトリは次のいずれかから取得できます。

推奨される列パターン

full_name（例: psf/requests）
repo（例: psf/requests）
repository（例: psf/requests）

代替パターン

owner と name（owner/name に結合）
org と repo_name（org/repo_name に結合）
repo_owner と repo_name（repo_owner/repo_name に結合）
html_url または url（https://github.com/owner/repo から owner/repo を抽出）

解析ルール

空白をトリムします。
.git サフィックスが存在する場合は削除します。
https://github.com/owner/repo/... を owner/repo に正規化します。
すべてのCSV間でリポジトリの重複を排除します。

CSVでサポートされている列が見つからない場合は、入力レベルのエラーを記録し、残りのファイルで続行します。

出力

出力CSV: `skill_md_scan_results.csv`

リポジトリごとに1行の単一CSV（マッチパスごとに複数行を出力するように設定した場合を除く）。

推奨列

repo owner/repo の正規識別子。
source_csv 元のSEART CSVのファイル名（マージされた場合は MULTIPLE）。
found true|false。
match_name 使用されたファイル名ルール（通常は SKILL.md）。
match_path マッチしたパス（例: /SKILL.md）。
default_branch デフォルトブランチ名（利用可能な場合）。
ref_scanned 使用されたブランチまたはコミット参照（例: HEAD または main）。
match_url ファイルが見つかった場合の正規URL。
match_sha GitブロブSHA（利用可能な場合）。
match_size_bytes サイズ（利用可能な場合）。
scan_method contents_api | code_search | sparse_checkout | local_clone。
http_status API呼び出しのステータスコード（該当する場合）。
error_type none | not_found | rate_limited | auth | network | invalid_repo | other。
error_message 短いエラーの詳細。シークレットは含めないでください。
scanned_at_utc ISOタイムスタンプ。
stars（オプション）
fork（オプション）
archived（オプション）

選別リストCSV（オプション）

include_negative_results=false の場合、出力自体が選別リストになります。それ以外の場合は、2番目のファイルを生成します：

skill_md_shortlist.csv（found=true の行のみを含む）

機能

1) SEART CSVフォルダの取り込み

ディレクトリ内のすべての .csv ファイルを検出します（再帰的オプションあり）。
堅牢な列検出でリポジトリ識別子を抽出します。
重複を排除し、正規のリポジトリリストに正規化します。

2) リポジトリの `SKILL.md` スキャン

このスキルは、レート制限を考慮した階層的戦略を使用します：

階層A（推奨）: GitHub Contents API

正確なパスがわかっている場合に最も高速でコストが低い。

デフォルトブランチの参照に対して、候補パス（デフォルト /SKILL.md）をチェックします。
200を「見つかった」、404を「見つからなかった」として記録します。

階層B（オプション）: GitHubコード検索（リポジトリ内のファイル名検索）

以下の場合にのみ使用：

サブディレクトリ内の SKILL.md を見つけたい場合。
大文字小文字を区別しないマッチングが必要な場合。
Contents APIのパスが不明な場合。

推奨されるクエリ形式：

repo:owner/repo filename:SKILL.md

階層C（フォールバック）: スパースチェックアウトによる浅いクローン

以下の場合にのみ使用：APIが利用できない、レート制限されている、またはGitHub Enterpriseで検索APIがサポートされていない場合。

可能な限り完全な履歴と大きなブロブを避けるフィルタリングされたクローンを実行します。
候補パスのみをフェッチするためにスパースチェックアウトを使用します。

3) 結果の出力CSVへのエクスポート

作業を失わないように、出力をインクリメンタルに（ストリーミングで）書き込みます。
決定論的な列を保証します。
既にスキャンされたリポジトリをスキップすることで、再開モードをサポートします。

ワークフロー

ステップ0: 前提条件

読み取り専用操作のみ。
多くのリポジトリをスキャンする場合は、より高いレート制限を得るためにGitHub認証を確保してください。

環境オプション（優先順位順に解決）：

--github-tokens ghp_tok1,ghp_tok2 CLIフラグ — マルチトークンローテーション用のカンマ区切りリスト（トークンあたり5000 req/hr）
--github-token ghp_tok CLIフラグ — 単一トークンの上書き
GH_TOKENS=ghp_tok1,ghp_tok2 — 環境変数、カンマ区切り（新しいマルチトークン変数）
GH_TOKEN=ghp_tok — 環境変数、単一トークン（後方互換）
GITHUB_TOKEN=ghp_tok — 環境変数、フォールバック単一トークン
GitHub CLI gh auth login — 対話型使用
認証なし — 60 コア req/hr のみ（バルクスキャンには不適切）

複数のトークンが提供された場合、src/github_client/ の TokenPool は自動的に：

各リクエストで、残りクォータが最も多いトークンを選択します。
X-RateLimit-* レスポンスヘッダーからトークンごとのクォータを更新します。
現在のトークンが使い果たされたら、次の利用可能なトークンにローテーションします。
すべてのトークンが使い果たされた場合、最も早いリセット時間までスリープします。
待機時間が設定可能な最大値を超える場合は、RateLimitExhaustedError を発生させます。

ステップ1: SEART CSVからリポジトリリストを構築する

入力CSVを列挙します。
各CSVに対して：
- リポジトリ列を検出します。
- owner/repo を抽出し正規化します。
- source_csv を追跡します。
すべてのファイル間で重複を排除します。

ステップ2: 事前チェック

トークンの存在を検証します（認証なしの場合は警告）。
オプションでレート制限のステータスを照会し、安全な同時実行数を設定します。

ステップ3: 各リポジトリをスキャン

各 owner/repo に対して：

（オプション）リポジトリメタデータを取得：
- リポジトリの存在を確認します。
- デフォルトブランチ、アーカイブ、フォーク、スターを記録します。
- フィルター（スター、フォーク、アーカイブ）を適用します。
階層Aを使用して SKILL.md をスキャンします。
有効で必要な場合は、より深い検索のために階層Bを実行します。
有効で必要な場合は、フォールバックとして階層Cを実行します。
単一の最適なマッチ（または設定に応じてすべてのマッチ）を記録します。
結果行をすぐに書き込みます。

ステップ4: 選別リストを作成する

found=true でフィルタリングします。
選別リストCSVをエクスポートします。

ステップ5: サマリーレポート

最後に、以下を報告します：

スキャンしたリポジトリの総数。
見つかった数と割合。
error_type ごとのエラーの内訳。
実効スキャンレートと、発生したレート制限。

使用例

例A: ルートパスのみをスキャン（高速）

入力：
- seart_dir = data/seart_csvs/
- search_paths = ["/SKILL.md"]
出力：
- outputs/skill_md_scan_results.csv

例B: リポジトリ内のどこでも `SKILL.md` を検索

入力：
- コード検索を有効にする。
- case_sensitive=false
出力：
- outputs/skill_md_scan_results.csv
- outputs/skill_md_shortlist.csv

例C: 部分的なスキャンを再開する

outputs/skill_md_scan_results.csv が既に存在する場合、既存のリポジトリをスキップして続行します。

運用上の制約とガードレール

読み取り専用

コミットをプッシュしたり、PRを開いたり、Issueを作成したり、リポジトリの内容を変更したりしないでください。
選択した出力フォルダ以外のユーザーディレクトリに書き込まないでください。

レート制限とポリシングスキャン

クローンよりもContents APIのチェックを優先してください。
以下の場合には、制限された同時実行数と指数バックオフを使用します：
- 403 セカンダリレート制限
- 429 リクエストが多すぎる
部分的な進捗を継続的に保存します。

データ最小化

フォールバックが必要な場合を除き、完全なリポジトリをダウンロードしないでください。
トークン、クッキー、または生の認証ヘッダーをログや出力CSVに保存しないでください。

再現性

scanned_at_utc と ref_scanned を記録します。
設定（パス、大文字小文字の区別、有効な階層）を出力と一緒に保持します。

エラー処理ルール

リポジトリ解析エラー

行を owner/repo に解析できない場合は、その行を破棄し、CSVごとに行レベルの解析エラーサマリーをログに記録します。

存在しない、またはプライベートなリポジトリ

リポジトリが404またはアクセスできない場合：
- error_type=invalid_repo または error_type=auth
- found=false

一時的な障害

ネットワークタイムアウト、5xx応答：
- バックオフして再試行
- それでも失敗する場合は、error_type=network としてマークして続行

レート制限

レート制限された場合：
- 同時実行数を減らす
- バックオフして再試行
- それでもブロックされる場合は、error_type=rate_limited として記録

推奨されるデフォルト設定

match_name = "SKILL.md"
case_sensitive = true
search_paths = ["/SKILL.md"]
include_negative_results = true
resume = true
concurrency = 8
有効な階層：
- 階層A: オン
- 階層B: オフ（必要な場合のみ有効）
- 階層C: オフ（必要な場合のみ有効）

完了条件

出力CSVが存在し、スキャンされたリポジトリごとに1行（または設定に応じて見つかったリポジトリのみ）が含まれていること。
found=true の行には、動作する match_url と match_path が含まれていること。
スキャンは、行を重複させることなく再開可能であること。
サマリー統計が報告され、エラーの内訳が利用可能であること。

後続処理のための注意事項

このスキルによって生成された選別リストは、後続のパイプラインステージへの入力として意図されています。例えば：

SKILL.md コンテンツのダウンロードと解析
構造化セクション（説明、機能、ワークフロー、制約）の抽出
リポジトリごとにエージェントが発見可能なスキルのデータセットの構築

後続のステージでは、SKILL.md のコンテンツを信頼できない入力として扱い、使用前に抽出されたテキストをサニタイズする必要があります。

お気に入りのAIに質問する

ドキュメント

説明