skill-fetch

Skill Fetch

複数のレジストリからエージェントスキルを並行して検索、スコアリング、インストールします。

使用するタイミング

• skill-eval フックが「MISSING EXTERNAL SKILL」を出力したとき
• 現在のタスクに、ローカルでは利用できないドメイン専門知識が必要なとき
• ユーザーが「fetch skill」「search for a skill」「install a skill」を要求したとき

重要なルール

1. 決定する前に skillsmp_get_skill_content をプレビュー目的で使わない — 検索の説明で十分です。インストールが失敗した場合のフォールバックとしてのみ使用してください。
2. 最初の結果で停止し、ゼロの場合のみ続行する（最大 5 ラウンド） — 1 件以上の結果があるラウンドは分析に進みます。
3. スキップを決定できるのはユーザーだけ — LLM が自分でインストールをスキップしてはなりません。
4. 常にプレーンテキストで対話する — AskUserQuestion を使用しないでください。分析を出力し、ユーザーが番号またはコマンドで返信するのを待ちます。
5. 1 ページにつき最大 5 件の結果を表示する — 完全な分析（内容、長所、短所、リポジトリ URL）を含め、ユーザーが情報に基づいた判断を下せるようにします。

プラットフォーム互換性

このスキルは 6 以上の AI コーディングエージェント（Claude Code、Cursor、Codex、Gemini CLI、Windsurf、Amp）で動作します。ツール名は自動的に適応されます。完全なマッピング表については references/platform-adapters.md を参照してください。

手順

ステップ 0: SkillsMP MCP セルフチェック（Claude Code のみ）

検索する前に、SkillsMP MCP サーバーが利用可能か確認します。

1. まず、遅延読み込みされたツールの読み込みを試みます: ToolSearch("skillsmp") を実行して、遅延読み込みされた SkillsMP MCP ツールを読み込みます。Claude Code では、MCP ツールはしばしば遅延読み込みされ（要求されるまで読み込まれません）、mcp__skillsmp__skillsmp_search のような名前空間付きの名前を持ちます。ToolSearch 呼び出しはこれらを解決します。
2. ToolSearch の後、skillsmp_* または mcp__skillsmp__* ツールが利用可能になったか確認します
3. 利用可能な場合 → ステップ 1 に進みます
4. まだ利用可能でない場合 → 次を実行します: claude mcp add --scope user skillsmp -- npx -y skillsmp-mcp-server
5. ユーザーに伝えます: 「SkillsMP MCP サーバーが登録されました。セッションを再起動すると利用可能になります。今は残りの 7 つのソースで検索を続けます。」
6. ステップ 1 に進みます（SkillsMP ソースは今回のセッションではスキップされますが、今後のセッションでは利用可能になります）

ツール名に関する注意: SkillsMP ツールは MCP 名前空間プレフィックス付きで表示されることがあります: skillsmp_search ではなく mcp__skillsmp__skillsmp_search。どちらの形式も動作します — 利用可能なほうを使用してください。

Claude Code 以外のエージェント: このステップをスキップしてください。SkillsMP ツールは Claude Code 専用です。

ステップ 0.5: API キーの読み込み（必須 — ステップ 2 の前に実行）

ソース 8〜9 には API キーが必要です。設定ファイルを読み込んで利用可否を判断します。

1. 今すぐ ~/.claude/skills/.fetch-config.json を読み込みます — ファイルを読まずにキーが存在しないと決めつけないでください
2. 想定される形式:

   {
     "SKILLHUB_API_KEY": "sk-sh-...",
     "SKILLS_DIRECTORY_API_KEY": "sk_live_..."
   }
   

3. 結果を記録します — ステップ 2b で使用する 2 つのフラグを設定します:
   • HAS_SKILLHUB_KEY: true/false
   • HAS_SKILLS_DIR_KEY: true/false
4. 設定ファイルが存在しない場合 → 両方のフラグ = false、ユーザーにファイルを作成できることを伝えます
5. 設定ファイルは存在するが特定のキーが欠けている場合 → そのフラグ = false

⚠️ よくある失敗パターン: LLM が設定ファイルの読み込みをスキップし、「キーなし」と決めつけます。これにより、キーが設定されている場合でもソース 8〜9 が誤ってスキップされます。常に最初にファイルを読み込んでください。

ステップ 1: 検索キーワードとソースの決定

URL モード: $ARGUMENTS が URL の場合（https://github.com/... または任意の https:// で始まる）、直接ステップ 3 のインストールフローにスキップします。

検索モード:

• $ARGUMENTS がある場合: そのまま検索語として使用します
• 検索語がない場合（自動トリガー）: フック出力の Suggested search terms を優先し、それ以外の場合はタスクコンテキストから 2〜3 件のクエリを抽出します

ステップ 2: 並列検索 — 全 9 ソース（必須）

⚠️ 必須: 9 つのソースすべてを必ず実行してください。9 つのソースすべてが結果を返すか失敗するまで、スコアリングに進んではいけません。

⚠️ よくある失敗パターン: LLM がソース 1〜2（SkillsMP）を実行して結果を得ると、ソース 3〜9 をスキップしてしまいます。これは誤りです。SkillsMP の結果だけでは不十分です — GitHub、ClawhHub、skills.sh、PolySkill には SkillsMP がインデックスしていない異なるスキルが含まれています。

⚠️ 実行順序: ステップ 2.5 に進む前に、ステップ 2a とステップ 2b の両方を完了しなければなりません。ステップ 2a だけでは不十分です。

ステップ 2a: SkillsMP ソースを実行する（1〜2）

#	ソース	ツール呼び出し	フォールバック
1	SkillsMP AI	skillsmp_ai_search × 3 クエリバリアント（並列）	MCP が利用できない場合はスキップ
2	SkillsMP キーワード	skillsmp_search(query)	MCP が利用できない場合はスキップ

ステップ 2b: SkillsMP 以外のソースを実行する（3〜9）— スキップしないでください

⚠️ ステップ 2a がすでに結果を返していても、これらのソースを必ず実行しなければなりません。これらのソースには SkillsMP にないスキルが含まれています。

#	ソース	ツール呼び出し	フォールバック
3	GitHub リポジトリ	gh search repos "{query}" --json name,description,url,stargazersCount,updatedAt --limit 5 --sort stars（「skill SKILL.md」を付加しないでください）	gh search code "{query}" --filename SKILL.md --limit 5
4	Anthropic Skills	gh search code "{query}" --repo anthropics/skills --filename SKILL.md --limit 5	gh api ツリーによるフォールバック
5	ClawhHub	npx -y clawhub search "{query}"	失敗時はスキップ
6	skills.sh	WebFetch("https://skills.sh/api/search?q={query}&limit=5")	Bash 経由の curl -s
7	PolySkill	npx -y @polyskill/cli search "{single_keyword}" --limit 5（クエリから最も具体的な単一キーワードを抽出してください — 複数語のクエリは 0 件を返します）	失敗時はスキップ（REST API なし）
8	SkillHub	HAS_SKILLHUB_KEY = true の場合（ステップ 0.5 より）: bash {SKILL_BASE_DIR}/scripts/fetch-skillhub.sh "{query}"。false の場合: npx -y @skill-hub/cli search "{query}" --limit 5（タイムアウト: 10000）	失敗時は CLI にフォールバック
9	Skills Directory	HAS_SKILLS_DIR_KEY = true の場合（ステップ 0.5 より）: bash {SKILL_BASE_DIR}/scripts/fetch-skills-directory.sh "{query}"。false の場合はスキップ。curl を直接使用したり WebFetch を使用したりしないでください。	ステップ 0.5 でキーが存在しないことが確認された場合のみスキップ

⚠️ ソース 8〜9 には、ステップ 0.5 が実行済みであることが必要です。 ステップ 0.5 がスキップされていた場合は、ソース 8〜9 をスキップ済みとして処理する前に、今すぐ ~/.claude/skills/.fetch-config.json を読み直してください。{SKILL_BASE_DIR} = このスキルのベースディレクトリ（スキルの読み込み時に上部に表示されます）。

詳細なパラメータ、レスポンス形式、クエリバリアントの例、curl フォールバックコマンドについては、references/search-sources.md を参照してください。

⚠️ 検索後チェックリスト（ステップ 2.5 に進む前に必須）:

スコアリングの前に、すべてのソースについて実際のステータスを記載したこのチェックリストを出力してください:

Step 0.5 config: HAS_SKILLHUB_KEY={true/false} HAS_SKILLS_DIR_KEY={true/false}
Sources queried: [1] SkillsMP AI ✅ [2] SkillsMP KW ✅ [3] GitHub ✅/❌ [4] Anthropic ✅/❌ [5] ClawhHub ✅/❌ [6] skills.sh ✅/❌ [7] PolySkill ✅/❌ [8] SkillHub ✅/❌ [9] Skills Dir ✅/❌

検証ルール — 進む前に戻って修正してください:

• ソース 3〜7 がすべて ❌ の場合 → 今すぐソース 3〜7 を再実行してください
• HAS_SKILLHUB_KEY=true なのに [8] が ❌ の場合 → 今すぐ bash {SKILL_BASE_DIR}/scripts/fetch-skillhub.sh を実行してください
• HAS_SKILLS_DIR_KEY=true なのに [9] が ❌ の場合 → 今すぐ bash {SKILL_BASE_DIR}/scripts/fetch-skills-directory.sh を実行してください
• ステップ 0.5 が一度も実行されていない場合（上記に設定行がない場合）→ 今すぐ ~/.claude/skills/.fetch-config.json を読み、その後ソース 8〜9 を再評価してください

すべてのソースが返った後 → 重複を排除し（references/search-sources.md を参照）→ ステップ 2.5 に進んでください。

ラウンド戦略（最大 5 ラウンド）: 「1 件以上の結果 → 停止」ルールはラウンドに適用されるのであり、個々のソースに適用されるのではありません。1 つのラウンド内では、9 つのソースすべてを照会しなければなりません。あるラウンドで 9 つのソースすべてが 0 件の結果を返した場合にのみ、より広いキーワードで次のラウンドに進んでください。あるラウンドでいずれかのソースが 1 件以上の結果を返した場合は、スコアリングに進んでください（別のラウンドを開始しないでください）。

ステップ 2.5: スコアリングとランキング

重複排除後の各結果について、品質スコア(0〜100)を計算します。詳細は references/quality-signals.md を参照してください。

スコアリング式: Total = Relevance(0-40) + Freshness(0-25) + Community(0-20) + Trust(0-15) + External Bonus(0-5)

補足ルックアップ: 上位 5 件の結果について、gh api repos/{owner}/{repo} --jq '{pushed_at,stargazers_count}' を使って更新日時と GitHub スター数を取得します。説明が正確に一致する高スター(≥50)の結果についてはルックアップをスキップしてください。gh api の呼び出しは最大 3 回までです。

グレードラベル: 🟢 85+ 強く推奨 | 🟢 70-84 推奨 | 🟡 55-69 検討の価値あり | 🟡 40-54 限定的 | 🔴 <40 非推奨

ステップ 3: 分析、選択、インストール

完全なインストールワークフローについては references/installation-guide.md を参照してください。

クイックリファレンス — 流れ:

1. 3a. ソート済みの結果を表示する(1 ページ 5 件、スコア + 長所/短所)
2. 3b. ユーザーの返信を待つ(インストールする番号、次ページは c、終了は skip)
3. 3c. インストール先を尋ねる(G=グローバル、L=ローカル) — 必須
4. 3d. インストールを実行する(SkillsMP → trust-but-verify、GitHub → バンドル全体を取得、SKILL.md だけでなく、その後すべてのファイルをインストール前にスキャン)。GitHub URL には scripts/fetch-skill-bundle.sh を使用してください。
5. 3e. インストール後の検証(ファイルの存在、frontmatter、競合チェック、バンドルの完全性、インストールされたすべてのファイルに対する SHA-256)
6. 3f. ~/.claude/skills/.fetch-metadata.json を更新する
7. 3g. 有効化し、ユーザーに確認する

⚠️ 重要: GitHub からインストールする場合、スキルとはそのディレクトリ全体を指します — SKILL.md に加えて references/、scripts/、assets/、templates/、prompts/、data/ などです。SKILL.md のみをダウンロードすると、それらのファイルに処理を委ねるスキルでは壊れたインストールになります。常に完全なバンドルを取得してください。

ステップ 4: インストールされたバンドルを精読する

インストールされたスキルは ディレクトリ であり、単一の SKILL.md ではありません。多くのスキルはコンテンツをサブディレクトリに分割しています — references/(ドキュメント)、scripts/(ヘルパー)、assets/、templates/、prompts/、data/、examples/ などです。SKILL.md だけを読むと、スキル作者がオンデマンドで読み込むことを想定している指示を見落とす可能性があります。

1. Glob を使ってインストール済みのツリー全体を一覧表示します: {install-path}/{skill-name}/**/*。
2. バンドルの完全性を検証します。 SKILL.md が相対パス(bash scripts/foo.sh、See references/bar.md、Load assets/template.json)を参照していて、それらのファイルが存在しない場合、インストールは不完全です — GitHub バンドルの取得を再実行してください(references/installation-guide.md §3d を参照)。
3. 現在のタスクに直接関連するファイルを読みます(最初の 30 行で関連性を確認してください)。これを references/ に限定しないでください — 関連するファイルは prompts/、templates/、または別のサブディレクトリにあるかもしれません。
4. 後続の計画に使用するため、主要な知識を要約します。

完了後、次を出力します: External skill installed successfully: {skill-name}

完了時のフレーズ

• 成功: External skill installed successfully: {name}
• スキップ: External skill fetch: user chose to skip installation.

追加リソース

合理化表とレッドフラグは references/interaction-patterns.md にあります。手順の省略を合理化しそうなときに参照してください。

• references/interaction-patterns.md — 出力テンプレート、ユーザー返信の処理、セキュリティレビュー
• references/quality-signals.md — 品質評価の観点、検索方法、ランキングアルゴリズム
• references/search-sources.md — ソース固有のコマンド、エラー処理、重複排除ルール
• references/platform-adapters.md — クロスプラットフォームのツールマッピング、インストールパス、フォールバック戦略
• references/installation-guide.md — 完全なステップ 3 のインストールワークフロー（3a〜3g）
• references/local-index.md — 検索前の重複排除のためのローカルスキル/プラグインスキャン実装
• scripts/fetch-skillhub.sh — SkillHub API 検索（キーを ~/.claude/skills/.fetch-config.json から読み取ります）
• scripts/fetch-skills-directory.sh — Skills Directory API 検索（キーを設定から読み取ります）
• scripts/fetch-skill-bundle.sh — 任意の GitHub の blob/tree/raw URL から完全なスキルバンドル（SKILL.md とすべての兄弟ファイル/サブディレクトリ）をダウンロードし、ディレクトリ構成を保持します