skill-selector

スキルセレクター

スキルの追加はディスク上の容量をほとんど使いませんが、コンテキストを消費します。慎重に選びましょう。

このスキルでは、次の2つの用途を分けて扱います。

1. 厳選カタログから選択 — 迅速で、見解が明確で、ほとんどの場合これで十分です。
2. 検索して評価 — より幅広く、時間がかかり、フェーズ1で適切なものが見つからない場合に限ります。

それぞれを別個の手順として実行します。カタログ内のスキルは事前に審査済みです。カタログ外のスキルは審査されていないため、採用前に明示的な評価が必要です。

使用するタイミング

• 新しいプロジェクトやリポジトリを始めるときに、適切なスキルをそろえたい場合
• 開発途中で、繰り返し行うタスクの種類が明らかになった場合（突然 Playwright が必要になったり、リリースの自動化が必要になったりしたとき）
• スラッシュコマンドや別のスキルから、まだインストールされていない後続のスキルが示された場合

使用しない場合：

• 一度限りで繰り返さないタスク — その場で解決します。二度と使わないスキルはインストールしません
• プロジェクトの apm.yml に関連するスキルがすでに記載されている場合 — 検索する前に再確認します

フェーズ1 — 厳選カタログ

カタログは references/catalog.md にあります。プロジェクトのシグナル（言語／ツール／プロセス）ごとに分類され、apm install の文字列が記載されています。

ワークフロー：

1. references/catalog.mdを読みます。
2. 3つの情報源からプロジェクトの手がかりを特定します。
   • リポジトリのファイル：package.json（Node）、moon.mod.json（MoonBit）、gleam.toml（Gleam）、flake.nix（Nix）、.github/workflows/（CI）、Playwright の設定、dotenvx のキーストア。
   • ユーザーが明示した意図：「X にデプロイする予定」「いずれ小さな npm ユーティリティを公開する」など、メッセージ内の手がかり。
   • CLAUDE.md の必須ルール：ユーザーレベルの ~/.claude/CLAUDE.md またはプロジェクトレベルの CLAUDE.md に記された継続的なルール（例：「タスクランナー：justfile」「lint：ast-grep」）は、シナリオの説明に記載がなくても手がかりとして扱います。必須ルールと明示された意図が食い違う場合は、インストール前にその不一致をユーザーに伝えます。提案では、レビュー担当者が水増しだと誤解しないよう、必須ルールに基づく項目に明示的なラベルを付けます（例：# from ~/.claude/CLAUDE.md: task runner = justfile）。
3. インストール前にユーザーの確認を得ます。候補を提案し、ユーザーが差し引けるようにします。スキルは多くするより少なくするのが基本です。スキルは会話のたびにコンテキストを消費します。
   • 非対話型のコンテキスト（サブエージェントへのディスパッチ、スクリプトによる自動化、バッチ実行）：提案を成果物として出力し、そこで終了します。選択は呼び出し元に委ねます。返ってこない確認を待って処理を止めてはいけません。
   • 使用中の言語に関するヒューリスティック：ユーザーが、カタログに <lang>-practice スキルがある言語（例：moonbit-practice、gleam-practice）で積極的にコードを書いている場合、そのスキルを含めます。その言語で書かれたバインディングまたは依存関係を1つ使っているだけなら、追加は保留します。
   • プラットフォーム名に関する注意事項：カタログの説明で特定の CI プロバイダー／ランタイム／クラウドに言及している場合：
     • プロジェクトのプラットフォームが一致する場合：そのまま採用します。カタログの項目で必要な情報はすでに得られるため、元の SKILL.md を再度読む必要はありません。
     • プロジェクトのプラットフォームが異なる場合：採用を決める前に、元の SKILL.md を読みます。中核となる機能は適用できる可能性があるため、その機能のためにインストールし、「integration glue N/A」と記します。プラットフォームが一致しないという理由だけで見送るのは誤りです。
     • 元の SKILL.md を読めない場合（ローカルにインストールされていない、upstream のクローンがない、ネットワークに接続できない）：確認を黙って省略してはいけません。提案で不確実性を明示します。例：「カタログの説明に基づいて <skill> を採用しています。SKILL.md は未確認のため、中核機能と統合部分の切り分けは検証できていません。」その後、ユーザーはインストールを確定する前に確認すべきかどうかを判断できます。確認を黙って省略すると、誤ったスキルの採用や、利用可能なスキルの却下という問題が残り、後続の手順では回復できません。
   • 対象外の項目：カタログで (out-of-band) とタグ付けされた項目は、公開 APM ではインストールできません（chezmoi ローカル、アクセス制限ありなど）。プロジェクトに有用であれば文章で言及しますが、apm.yml には追加しません。
4. APM でインストールします。まず apm-usage を読み、apm.yml の正確な構文を確認します。マニフェストの形式は単純ではないため、このスキルだけを根拠にフィールド名を推測してはいけません。
   • プロジェクトスコープ：apm.yml を編集し、apm install を実行します。apm.lock.yaml をコミットします。
   • グローバルスコープ：apm install -g <repo>/<path> を実行し、~/.apm/apm.yml を確認します。
   • targets: 宣言は必須です。 APM 0.12+ では、リポジトリのルートにマーカー用ディレクトリ（.claude/、.github/ など）がない場合、デフォルトのターゲットにはフォールバックしません。明示的な選択を求めて apm install がエラーになります。apm.yml に targets: [claude]（またはホストハーネスに応じた値）を必ず記述し、ディレクトリの自動検出に頼ってはいけません。
   • targets: は、デプロイ先ディレクトリを厳密に制限するものではありません。 targets: [claude] を指定していても、APM 0.12+ は .claude/skills/ と併せて .agents/skills/ にも書き込む場合があります。apm install の出力（Skill integrated -> ...）を確認し、以下の gitignore の判断では、一覧に表示されたすべてのパスをデプロイ先として扱います。
   • バージョンの固定：カタログの項目にはタグがありません。apm.yml をコミットする前に、apm view <repo>（または upstream リポジトリのリリースページ）で具体的なタグまたは SHA を確認します。浮動参照は「よくある間違い」に記載されています。
5. 最初のコミット前に gitignore の方針を決めます。 apm install は apm_modules/ を .gitignore に自動追加しますが、デプロイ先は追加しません。次のいずれかを選び、一貫して適用します。
   • デプロイ先をコミットする（.claude/skills/、.agents/skills/ など）：リポジトリが自己完結し、チームメンバーや CI は apm install を実行せずにクローンできます。コストとして、ファイル数が大幅に増えます（最近の utels のインストールでは、スキル7つで約700ファイル）。チームメンバーが APM を利用できない可能性がある場合や、PR でスキルの内容をレビュー可能にしたい場合に選びます。
   • デプロイ先を gitignore に追加する：リポジトリを軽量に保てますが、チームメンバーはクローン後に apm install --frozen-lockfile を実行します。apm install の出力に表示された正確なパス（例：.claude/skills/、.agents/skills/）を追加します。注意点として、プロジェクトが同じディレクトリ（.claude/skills/<local-skill>/ など）にローカルスキルも保持している場合は、ディレクトリ全体ではなく、APM 管理下のサブパスだけを gitignore に追加します。
   • いずれの場合も、apm.yml と apm.lock.yaml は必ずコミットします。ロックファイルがないとインストールを再現できません。デプロイ先を gitignore に追加するかどうかで変わるのは、生成された成果物を git に含めるかどうかだけです。
   • APM スキルを初めてリポジトリに導入する際は、どちらの方針にするかユーザーに提案します。黙って決めてはいけません。ファイル数の増加と、クローン後のインストールの手間のどちらを選ぶかは、リポジトリごとに異なる妥当なトレードオフです。
6. 解決されていないニーズがあれば、フェーズ2に進みます。検索語がすでに頭に浮かんでいても、フェーズ1を省略してはいけません。カタログを確認する方が手間がかかりません。

フェーズ 2 — 検索と評価（skill-finder に委任）

フェーズ 2 は skill-finder スキルが担当します。次の条件をすべて満たす場合にのみ、起動してください。

• フェーズ 1 に候補がない（カタログを確認しても、約30秒以内に該当する項目が見つからない）。
• ニーズが繰り返し発生するものであり、1回限りのセットアップ作業ではない。1回限りのひな形作成（Vite／React の初期化、単発の設定変換、場当たり的なデータ移行）は、その場で対応します。
• ニーズが単なる潜在的な兆候ではなく、現在の課題または近いうちに行う作業として明示されている。リポジトリに Rust サービスがあるものの、現在スキルが必要となる質問につながっていないのであれば、それだけでフェーズ 2 を正当化することはできません。繰り返し発生するニーズが表面化するまで待ってください。

3つの条件のいずれかを満たさない場合は、何もしないでください。エスカレーションする前に、上記の「使用しない場合」セクションを読み直してください。

フェーズ 2 を実行するには、ユーザーに「フェーズ 1 のカタログに適合するものがありません。ソースを横断して検索するために skill-finder を起動しますか？」と伝え、明示的な許可を得てから進めてください。skill-finder は、ソースを横断して調査し（Anthropic 公式 → claude-skill-registry → VoltAgent → ComposioHQ → Superpowers → GitHub トピック）、同じ評価基準を適用し、必須の waxa 評価を通じて採用を判断します。このワークフローをその場で重複して実行しないでください。

フェーズの境界 — 混同しない

2つのフェーズは、それぞれ異なる問題を解決します。

• フェーズ 1 は、幅広さを信頼性と引き換えにします。カタログは厳選されています。信頼してください。
• フェーズ 2 は、信頼性を幅広さと引き換えにします。明示的な評価で補ってください。

よくある失敗：フェーズ 1 に playwright-test があるのに、「GitHub で Playwright スキルを検索してみます」とフェーズ 2 から始めること。必ず最初にカタログを確認してください。

逆の失敗：カタログに本当に適切なものがないのに、フェーズ 1 の項目を無理に当てはめること。約30秒確認しても該当する項目がなければ、エスカレーションしてください。近いものの適合しないスキルでインストール一覧を埋めないでください。

カタログのメンテナンス

• カタログはこのスキルの一部です。mizchi/skills と、参照している上流のスキルリポジトリでスキルが追加または削除された場合は、カタログも同期してください。
• フェーズ 2（skill-finder）で見つかったスキルは、2つ以上のプロジェクトで問題なく使用され、waxa 評価に合格した後、カタログに追加できます。
• カタログが古く感じられる場合は、skill-finder に頼る前に mizchi/skills README と照合してください。

よくある間違い

間違い	対処
「念のため」スキルをインストールする	しないでください。スキルを追加するたびに、会話で使えるコンテキストが減ります。近いうちに必要な作業がある場合にのみインストールしてください。
カタログを確認せず、すぐに GitHub 検索に進む	まずカタログを読み直してください。これを避けるためにカタログがあります。
テストせずにフェーズ 2 のスキルを採用する	skill-finder では、採用前に waxa 評価への合格が必須です。省略しないでください。説明が実態と異なることもあります。
プロジェクトのスコープに apm.yml の浮動参照を使う	タグまたは SHA を指定してください。機能開発の途中で参照先が変わると、それ自体がデバッグ地獄になります。
以前却下した同じスキルを四半期ごとに再評価する	却下した理由をリポジトリ内に記録してください。すでに確認したものを再検索しないでください。
APM のデプロイ先を黙ってコミット（または黙って gitignore）する	選択を明示してください。手順 5 を参照してください。既定でコミットするとリポジトリが肥大化するおそれがあり、既定で無視すると APM を使っていないチームメイトの環境で動かなくなるおそれがあります。
targets: [claude] によってデプロイ先が .claude/skills/ だけになると思い込む	APM 0.12+ では .agents/skills/ にも書き込まれる場合があります。apm install の出力を確認し、表示されたすべてのパスをデプロイ先として扱ってください。
フェーズ 1 のカタログにすべてが網羅されていると考える	約30秒確認しても該当するものがなければ、フェーズ 2 にエスカレーションしてください。無理に当てはめないでください。

関連項目

• skill-finder — フェーズ 2 の担当。カタログに適合するものがない場合に、ソースを横断して調査し、waxa 評価を実施します
• apm-usage — 実際の apm install の構文とマニフェスト形式
• empirical-prompt-tuning — 候補スキルを採用前にテストする方法
• superpowers:writing-skills — 既存スキルに適合するものがない場合に、適合しないスキルを採用するのではなく、新しいスキルを作成します
• chezmoi-management — 非公開にする必要があるスキル向け（APM と chezmoi の境界）