e9tgldr/skill-router

スキルルーター

現在、ここには約170のスキルがインストールされており、その質と範囲は大きく異なり、いくつかは互いにほぼ重複しています（「一般的に見えないようにする」デザインスキルが3つ、impeccableのコピーが2つ、xlsxとxlsx-dshが隣接）。不適切なスキルを選ぶことは、ここで可能な最も高価なミスです。間違ったスキルはそのコンテキスト全体を消費し、回答を目標から逸らせます。一方、スキルをまったく使わない方が、通常は間違ったスキルを使うよりも優れています。

したがって、最初にルーティングし、その後に作業を行います。このファイルはルーティング手順です。これは安価です（1回のファイルスキャン、1回か2回のツール呼び出し）であり、スキルリストからの推測を置き換えます。この手順はインストールに依存しません。以下のカウント、名前、ファミリーは、これが作成されたカタログを説明しており、検索は見つけたカタログに正規化されます。

1. タスクを読んでから何も触らない

以下の問いに、それぞれ1行で黙って答えてください。これらはルートを決定し、成果物を決定するものではありません。

• 何が生成されるか？ ファイル（docx/xlsx/pdf/pptx/png）、実行コード、決定、メッセージ、計画。
• どのドメインか？ Webフロントエンド、バックエンド、データ、ドキュメント、デザイン、ビデオ/アニメーション、VR、運用。
• 既存の成果物はあるか？ グリーンフィールド vs. 誰かのコードの修正 — これにより、ルートが構築スキルから監査/レビューおよび理解優先スキルに変わります。
• 誰が出力を読むか？ 投資家、教師、チームメイト、コンパイラ。対象読者によってライティングスキルが変わりますが、技術スキルは変わりません。

リクエストが1文の純粋な意図（「何かクールなものを作って」）である場合、それもルーティングシグナルです。つまり、まだスキルを選択できず、質問が優先されることを意味します（ステップ6）。

2. 高速パス — ルーティングテーブルを確認する

references/task-types.md（このスキルディレクトリからの相対パス）を読んでください。最初のテーブルは、約40の一般的なタスク形状を1画面で検証済みのスキルチェーンにマッピングしています。2番目のテーブルは、推測できない名前を持つニッチなツール（animation-vocabulary、cdn-caching、vercel-connect）をリストしています。これらは誰も検索しないため、何も適合しないと結論付ける前に確認してください。

• 一致が見つかった場合 → そのチェーンでステップ4に進みます。検索も行わないでください。テーブルが答えであり、再度検索するのはトークンを浪費するだけです。
• 一致しない場合、または部分的な一致の場合 → ステップ3。
• テーブルに存在しないスキルがリストされている場合（異なるインストール、異なるハーネス、新しいマシン）→ テーブルを完全にスキップしてステップ3に進みます。テーブルは1つのインストールのマッピングであり、検索は任意のカタログで機能します。--doctorで確認してください。

3. カタログを検索する

1つのコマンドで、モデルは不要です：

# パスはこのスキルのディレクトリからの相対パス
node scripts/find_skills.mjs "ランディングページが一般的に見える" -n 8
node scripts/find_skills.mjs --doctor      # どのルートがスキャンされたか、何が見つかったか

これは、インストールされているすべてのスキルを名前と説明でスコアリングします（IDF重み付けにより、稀な単語がuser/code/whenよりも優先されます）。さらに、必要なスキルと語彙を共有しない言い回しのためにキュレーションされた概念レイヤーを追加します。上位の一致をSKILL.mdパスとともに出力するか、何も適合しない場合はNO GOOD MATCHと出力します。

うまくクエリする方法：

• タスクの名詞を使用し、ユーザーの文は使用しないでください：スプレッドシート チャート csv、これをグラフ付きの何かにできる？ではありません。
• 1つの長いクエリではなく、2～3の異なる角度で実行してください。成果物の角度（ピッチデッキ）、ドメインの角度（投資家 資金調達）、問題の角度（テキストがテンプレートっぽい）。必要に応じて1回のbash呼び出しでまとめて実行してください。
• --explainは、各結果がなぜそのようにランク付けされたかをトークンごとに出力します。結果が間違っているように見える場合に、原因を推測する代わりに使用してください。
• 各結果には[strong]、[likely]、または[weak]のタグが付けられます。[weak]は、ルーターが1つの偶然の単語から推測していることを意味します — 提案として扱い、答えとして扱わず、自身の判断を優先してください。すべての結果が弱い場合、スクリプトはそのように通知します。
• --allはカタログ全体をダンプし、--name pdfは1つの名前をパスに解決し、--jsonは機械可読な出力を提供し、-n 20はリストを広げて次点を表示します（適切に表現されていないクエリの場合、正しい答えが4位であることがよくあります）。
• 結果はランク付けされており、絶対的なものではありません。あなたが選択します。
• スクリプトはこのスキルのscripts/ディレクトリにあります。ハーネスが絶対パスを公開している場合はそれを使用し、そうでない場合は最初にスキルディレクトリにcdしてください。
• 存在するものすべてをインデックス化し、固定リストではありません。ハーネス全体で通常のユーザーおよびプロジェクトごとのスキルディレクトリ（~/.pi、~/.claude、~/.codex、~/.agents、~/.cursor、さらに<cwd>/skillsおよびプラグインnode_modules）をスキャンします。SKILL_ROUTER_ROOTS=/a/skills:/b/skillsまたは--root /a/skillsで他の場所を指定します。慣れないマシンでは、最初に--doctorを実行してください。すべてのルート、その存在の有無、寄与したスキル数、重複名、解析できなかったSKILL.mdファイルをリストします。新しいカタログに概念やゲートは必要ありません — これらは語彙ランキングの上に追加されるオプションのブーストであり、ゼロでも検索は名前と説明でランク付けされます。

スクリプト自体が利用できない場合、または検索がもっともらしい結果を2回返さない場合は、システムプロンプトリストから~/.pi/agent/skills/の説明を読むことにフォールバックしてください。停止したり、5つのSKILL.mdファイルを開いてどれかが当たるのを期待したりしないでください。

4. 選択 — チェーンを短く保つルール

1. プロセスは実装より優先。 作業の実行方法を設定するスキル（ブレインストーミング、計画作成、体系的なデバッグ、テスト駆動開発、スキル作成）は、出力の見た目を設定するスキル（デザイン、docx、nextjs）より先にロードします。プロセススキルは、次の実装スキルをロードするように指示することがよくあります。それに従ってください。

2. 最大3スキル。 1つが通常、2つが一般的、3つが上限です。4つ目は、あなたが決定する代わりに収集していることを意味します。

3. ファミリーごとに1つ。 同じファミリーの2つのメンバーを決してロードしないでください。最初の列を選択してください：

   ファミリー	1つを選択
   フロントエンドの味 / アンチジェネリック	design-taste-frontend、ui-craft、impeccable、frontend-design、craft
   重複コピー	impeccable（agents/）をimpeccable-dshよりも優先；xlsxをxlsx-dshよりも優先；kimi/*をdsh/*よりも優先（ただしdshの方が明らかに特化している場合を除く）
   ドキュメント形式	ファイルに完全に一致するもの：docx、pdf、pptx、xlsx
   モーション	animate（Web）、animate-expo（React Native）— 両方は不可
   バックエンド	backend-patterns、create-a-backend、api-design — 最大2つ
   クエスト / VR	hz-*ファミリー + metavr-cli；常にhz-quest-verify-firstから開始

4. プラットフォームゲートを尊重する。 hz-*、portal、metavr-cliはQuest/VRコンテキストを必要とします。cloudbaseはCloudBaseを必要とします。kimi-webbridge / kimi-cuは実際のブラウザまたはデスクトップGUIを必要とします。タスクがプラットフォームを指定していない場合、言葉がどれだけ一致しても、そのスキルは適用されません。

5. 正当化するか拒否するか。 各候補について、1つの節：なぜこれなのか。節が「同じ言葉に言及しているから」なら、拒否してください。2つのスキルが語彙を共有していても、異なるマシン向けである可能性があります。

6. 「なし」は有効な回答です。 何も基準をクリアしない場合は、それを一言で述べ、自身の判断でタスクを実行してください。スキルがないことは、半分しか関連していないスキルを起動する理由にはなりません。

7. ピボット時にのみ再ルーティングする。 同じワークフロー内の新しいサブタスクは、新たな検索をトリガーしません。ドメインの変更（ユーザーが「実際にデッキにして」と言う）はトリガーします。

5. 1行でアナウンスし、次に進む

作業を行う前に、ルートを一度述べてください：

design-taste-frontend（アンチテンプレートランディングページ）→ ヒーローにanimateを使用。 コピーライティング部分に適合するスキルはありません。自分で書きます。

その行のルール：1～2文、名前と理由のみ。スキルインベントリについてのエッセイや、「このタスクのために以下のスキルを選択しました。なぜなら…」は不要です。ユーザーは決定を見たいのであって、審議を見たいのではありません。ルートが異常である場合、またはテーブルから意図的に逸脱している場合、それは追加の節を設ける価値のある唯一のことです。

6. 作業を妨げるものだけを尋ねる

ここでルーティングの価値が発揮されます。選択したスキルは、何を知る必要があるかを教えてくれます。したがって、それらの質問を — そしてそれらの質問だけを — してください。

以下の場合にのみ、そしてその場合にのみ質問してください：

• タスクに2つ以上の真に異なる成果物がある場合（「ポスター」はPNGまたはスライドデッキの可能性があり、ファイルが異なる）、
• 対象読者または形式が不明であり、コンテキストから推測できない場合、
• 選択したスキルの指示自体が、ユーザーが所有する必要がある決定（ブランド、予算、認証情報、本番データ vs. モックデータ）を必要とする場合、
• ルートが実際のコストがかかるか、本番環境に影響を与える場合。

以下のことを尋ねないでください：

• どのスキルを使用するか — それはこのスキルの仕事です。結果について尋ね、ルーティングは回答に従わせてください。
• リクエストがすでに回答していること、コードベースやファイルが答えていることは何も。
• 適切なデフォルトでカバーできることは何も。デフォルトを選択し、アナウンス行でどのデフォルトを選択したかを伝え、先に進んでください。このユーザーは、ターンバイターンの確認よりも、長い無人実行を好みます。

形式：1回のask_user_question呼び出し、最大3つの質問、各質問に2～4の選択肢、推奨オプションを最初に「(推奨)」というラベルで、各オプションにそれが何を約束するかを1行の短い文で。最初のアンケートの直後に2つ目のアンケートを重ねないでください。回答が新しい質問を生じさせる場合は、別の往復よりも適切なデフォルトを優先してください。

ロードしたスキルに独自の探索や質問フェーズがある場合（ほとんどのデザインおよび計画スキルにはあります）、独自の質問を発明する代わりにそれを実行してください。2回連続の質問ラウンドは、遅延と解釈されます。

7. ロードして実行する

• readツールを使用して、SKILL.mdを検索で返されたパスで完全に読んでください。斜め読みしたスキルは斜め読みの出力を生み出します。

• references/、scripts/、assets/へのパスは、そのスキルのディレクトリからの相対パスで解決してください。検索出力はファイルを出力するため、親ディレクトリがスキルルートです。

• スクリプトは記述されたとおりに実行してください。スクリプトが文書化されていない引数を必要とする場合は、独自の実装で代用するのではなく、その旨を述べてください。

• スキルが優先されます。 ロードされると、その指示は、作業の実行方法に関するこのファイルの意見や一般的なベストプラクティスを上書きします。このファイルはそれを選択しただけです。

• ロードしたスキルが「最初にユーザーに尋ねる」または「コードを書く前に計画する」で始まる場合は、それを行ってください。プロセススキルにルーティングしてからそのプロセスをスキップすることは、ルーティングしないことよりも悪いことです。

• 作業の途中でスキルが間違っていたことに気付いた場合は、率直にその旨を述べ、再ルーティングしてください（ステップ4）。間違ったスキルを静かに回避することは失敗モードです。

• 修正を記録して、同じ間違いを二度と繰り返さないようにしてください：

  node scripts/find_skills.mjs --learn "<失敗した言い回し>" <正しいスキル>
  node scripts/find_skills.mjs --wrong "<失敗した言い回し>" <間違ったスキル>
  

  ユーザーがルートを拒否した場合、ロードしたスキルが間違ったツールであることが判明した場合、または検索が見逃したため手動でルーティングする必要があった場合には、常にこれを行ってください。学習された修正は、将来の同様のクエリで語彙スコアを上回り、インストールとともに移動します。これにより、このルーターはこれまで見たことのない環境で改善されます。

8. 終了

最後に1行：使用されたスキルと、成果物がどこに配置されたか。その後停止します。スキルの内容の要約、ルーティングの説明の申し出は不要です。

メンテナンス — ルーターを壊さずに変更する

ルーターは雰囲気ではなくスコアで評価されます。scripts/eval_routing.mjsには80の現実的なクエリが含まれており、それぞれに真に受け入れ可能な答えであるスキルのセットと、12のゲートケース（一般的なReactクエリがQuestスキルを表面化させてはならない）があります。変更の前後に実行してください：

node scripts/eval_routing.mjs
# スコア: 80/80 (100.0%)  ゲートリーク: 0
node ... --verbose      # ケースごとのランキング
node ... quest          # 一致するケースのみ

node scripts/smoke_portable.mjs   # 外部カタログ + 学習 + 600スキル規模

smoke_portable.mjsは移植性テストです。このルーターがこれまで見たことのないドメイン（Kubernetes、Rust、Salesforce、Terraform…）で16のスキルを発明し、ランキング、言い換えの頑健性、ポータブルゲート、学習、重複名、空のカタログ、スペースを含むパス、SKILL_ROUTER_ROOTS、および600スキル規模の実行をチェックします。スコアリングを変更する場合、両方のスイートがグリーンのままである必要があります。evalは既知のカタログでの品質を保証し、smokeは未知のカタログでの動作を保証します。

スコアを上げる変更は改善であり、スコアを下げる変更は、コードがどれだけきれいに見えても回帰です。期待されるスキルがインストールされていないケースはスキップされ、失敗とは見なされないため、スイートは任意のマシンで実行できます。

実際のタスクのルーティングがうまくいかない場合、それを説明する最も安価なレイヤーで修正してください：

1. 同じアイデアに対する間違った言葉 → find_skills.mjsにキュレーションされたCONCEPTSルールを追加します（when正規表現 → boostスコア、オプションのunless拒否権とdemote）。これはスキルと語彙を共有しない意図のためのレイヤーです：「漠然としたアイデア、仕様なし」→ brainstorming。 1回限り？ これに手を出さないでください — 代わりに記録してください（--learn）。CONCEPTSは一般的な動作のためです。メモリは「この言い回し、このスキル」のためです。
2. 繰り返し発生するタスク形状 → references/task-types.mdに行を追加します。クエリ時にコストはかからず、高速パスは検索を完全にスキップします。
3. ノイズの多い隣人に負け続けるスキル → DEMOTEに追加するか、ノイズの多いスキルに概念内でdemoteを与えます（例：dashboardだけではui-craftをui-craft-dense-dashboardで打ち負かしてはならない）。
4. 一般的なクエリに漏れ出すプラットフォームスキル → 対象となるために存在しなければならない言葉でGATESを拡張します。
5. ユーザーが修正したルート → --learn / --wrong、そして次に進みます。時々--memoryを確認してください。同じスキルが同じ種類の言い回しに対して修正され続ける場合は、パターンをCONCEPTSに昇格させ、エントリを--forgetしてください。

まず、失敗するクエリをCASESに追加し、それが失敗するのを確認してから修正してください。書き留めていないクエリでスコアリングを調整しないでください。そうすると、ルーターはあなたの例では優れているが、ユーザーの例では劣悪になるからです。

レッドフラグ — あなたは正当化しています。やめてください。

思考	現実
「これは単純だ。ルーティングは不要」	高速にルーティングし、高速に実装する。高速パスは検索を完全にスキップします。