Claude Code スキルの誤発火を防ぐ「ルーター集約」設計

ども！最近 .claude/skills/ の中身が増えすぎて整理に追われている龍ちゃんです。

スキルって、増えてくると狙ったやつが発火しなくなるんですよね。ぼくの .claude/skills/ はいま 15 個くらい。とくにレビュー系が 5 個ほど並んだ頃から、しっかり指示しないと違うレビューが走るようになって、「レビューして」の一言がもう信用できなくなりました。

今日は、その問題を複数のスキルを 1 つの “ルーター” に集約して、発話で振り分けるようにして解決した話をします。スキルを消して減らすんじゃなくて、束ねて減らす。このプロジェクトのレビュー系スキルで、実際にやったやつです。

1 スキルが増えるほど誤発火する：budget は静かに削れていく
2 文脈で束ねる＝ルーター Skill
- 2.1 ロジックは agent へ、ナレッジは references/ へ
- 2.2 で、束ねたら何が変わったか
3 ルーターにすべきか、独立スキルのまま置くか — 判断軸
4 関連記事

スキルが増えるほど誤発火する：budget は静かに削れていく

そもそも、なんでこんなに増えたのか。レビュー観点を思いつくたびに、スキルを 1 個ずつ足していったからです。技術的な正確さ、文章の質、SEO、競合比較……「観点が 1 個＝スキルが 1 個」でやっていたら、レビュー系だけでみるみる膨らみました。

そして、痛みが 2 つ出てきます。

1 つめは、表に出る痛み＝誤発火。似た description が並ぶと、Claude Code がどれを動かすか迷うんです。「レビューして」と言っても狙ったのと違うレビューが走る。毎回しっかり指示を足さないと、思ったスキルが発火しない。ただこれは、動いた結果が変だからすぐ気づけます。

2 つめは、気づけない痛み＝character budget。スキルの description は常時コンテキストに積まれていて、スキルが増えるほど膨らみます。そして budget を超えると、Claude Code は description を自動で切り詰める。マッチに必要なキーワードごと削られて、自分は何も変えていないのに、ある日スキルが静かに発火しなくなる（公式ドキュメントにも “descriptions are shortened to fit the character budget, which can strip the keywords Claude needs to match your request” と明記された挙動です）。/doctor を叩けば budget 超過と影響スキルは見えますが、意識しないと気づけません。誤発火と違って「壊れたことにすら気づきにくい」のが、こっちのタチの悪いところです。

budget の文字数や仕組みを深掘りすると長くなるので、ここでは「個数が増えると description が削られて発火が劣化する」という前提だけ。詳しくは別記事「『Skill listing will be truncated』の正体と直し方」で。

表の痛みも裏の痛みも、根っこは同じ「スキルの個数」でした。だったら、個数そのものを減らせばいい。冒頭で言った “束ねて減らす” を、ここから具体的に見せていきます。

文脈で束ねる＝ルーター Skill

ルーター Skill の役割は自分で処理しないこと。発話の修飾語を読んで、適切な sub-agent を選び、Agent tool で起動するだけです。

ポイントは、スキルの description は常時コンテキストに載り、character budget を食うということ。スキルが N 個あれば N 個分が積まれ、似た発火条件どうしが競合して誤発火します。ルーターにすれば、スキルとして登録するのは 1 個です。常時載る description も 1 個分に減ります。各機能のロジックは呼ばれたときに別コンテキストで動く agent へ、ナレッジは必要なときだけ読む references へ逃がしてあるので、ルーター本体（＝常時載る description）は薄いまま保てます。

つまり、発火条件を 1 つに統合したから誤発火が消え、常時載る description が N→1 に減ったから budget が空く。この 2 つは別々の効果じゃなくて、「発火条件＝description を 1 つにまとめた」ことの裏表なんですよね。

具体例で見てみましょう。僕が束ねたのはブログ記事のレビュー系でしたが、仕組みはどんなレビューでも同じです。なのでここは、エンジニアに一番馴染むであろうコードレビューで説明します。

セキュリティ・パフォーマンス・フロント・バックエンド……観点ごとに別々のスキルを作る代わりに、1 つの code-review ルーターにまとめて、発話で呼び分ける。こんなイメージです。

---
name: code-review
description: |
  コード (src/**) を編集している文脈で発火するレビュー router。
  「レビューして」「セキュリティ見て」「フロントだけ」「バックだけ」
  「パフォーマンス見て」「全部見て」等の発話で発火する。
  発話の修飾語から起動する sub-agent を選択し、Agent tool で並列起動する。
allowed-tools: Read, Glob, Agent
---

発話に含まれる語	起動する sub-agent
（修飾なし）「レビューして」	security + performance + readability（並列）
「セキュリティ見て」	security-review のみ
「フロントだけ」	frontend-review のみ
「バックエンドだけ」「API だけ」	backend-review のみ
「パフォーマンスだけ」	performance-review のみ
「全部見て」	用意したレビュー全部を並列

「レビューして」だけで 3 エージェントが並列で走る！これが Slash Command 単体にはない強みです。スラッシュコマンドは 1 回の呼び出しで 1 つの処理ですが、ルーター Skill は複数 sub-agent を同時に走らせられます。

以前書いた「Claude Codeのドキュメント検索を極力さぼれるようにした話」も、サブエージェントに処理を委譲して use_when で呼び出す設計で、考え方が重なります。

ロジックは agent へ、ナレッジは references/ へ

ルーター SKILL.md 自体は薄く保ちます。そして束ねるのは sub-agent だけじゃありません。「どう処理するか」のロジックは agent へ、「何を見るか・どう使うか」のナレッジは references/ 」と、役割で 3 層に分けます。

ルーター SKILL.md（薄く）── 発火条件 + 修飾語 → 振り分けだけ
    ↓ 呼び出す
.claude/agents/*.md ──────── 処理のロジック本体
    ↓ 必要なときだけ読む
skill/references/ ────────── ナレッジ（観点リスト・チェックリスト・使い方手順）

たとえば security-review なら、「見るべきセキュリティ観点」のチェックリストを references/ に置いておく。agent はそれを必要なときだけ読みにいきます。観点を足したいときは references を 1 ファイル直すだけです。SKILL.md にも agent 本体にもベタ書きしないから、常時のコンテキストは増えないし、ナレッジの管理も一箇所で済むんですよね。

ちなみに、処理を全部 agent に渡す必要はありません。「ここはメインの会話の流れのまま、途中を見ながら進めたい」という処理もありますよね。そういうときは agent に移譲せず、手順を references/ に書いておいてルーター自身（メインコンテキスト）に実行させる。こうすれば、今までメインでやっていた作業を、使用感を変えないままルーターに取り込めます。agent に切り出すか、references の手順としてメインで回すかを処理ごとに選べる、ということですね。

この「使うときだけ読み込まれる」挙動は、公式でいう Progressive Disclosure です。仕組みの詳細は公式に譲りますが、references をいくら厚くしても、常時のコンテキストは太らない。だから観点もチェックリストも手順も、遠慮なく references 側に積んでおけるんですね。

で、束ねたら何が変わったか

狙ったスキルがちゃんと発火する。これが当たり前にできるようになりました。スキル発火後にワンアクションが必要になりましたが、面白いのはその先です。

ルーターのほうから提案してくるようになったんですよね。文脈を読んで「これ、レビューしときましょうか？」と向こうから振ってくる。意図どおりならそのまま「お願い」で済むし、こっちが思いついてなかった使い道まで「こういうのにも使えますよ」と教えてくれる。おかげでレビューを頼むときの解像度がぐっと上がりました。雑に「レビューして」と投げても、文脈に合ったやつが返ってくるんです。

あと、これは完全に狙ってなかった副産物なんですが、メンテも楽になりました。

束ねる前は、スキルを名前のプレフィックスで分類していました。review-xxx、blog-xxx、みたいに。でもこれ、いざ「この観点を直して、その知見をあっちにも反映したい」となったとき、関連ファイルがパスのあちこちに散っていて「どれとどれを見ればいいんだっけ」になるんですよね。ルーターにしてからは「レビュー関連はこの 1 か所」と文脈でまとまっているので、直したいものも、関連する作業も、一発で辿れる。情報の在処がはっきりしました。

ルーターにすべきか、独立スキルのまま置くか — 判断軸

集約すべきかどうかは 1 問で判断できます。

発火する文脈と修飾語が共通か？

YES なら集約候補です。

目的が近い（レビュー系・調査系・変換系）
同じファイル文脈で発火する（「ブログ記事を編集中」など）
修飾語で選べる（「ぶった切って」「論理だけ」のように呼び分けられる）

NO なら独立スキルのまま置いていいです。

発火する文脈がまったく違う
単独で完結して他と競合しない

過剰集約の罠にも触れておきます。何でも 1 つに詰めると description が「全部入り」で逆に曖昧化して、発火精度が落ちるんですよね。ルーターは「文脈」で束ねるのが基本で、無関係な機能を 1 個に混ぜるのは逆効果です。

判断早見表をまとめると：

条件	判断
発火文脈が同じ（例：ブログ編集中）	ルーターに集約
修飾語で呼び分けられる	ルーターに集約
目的が近い（レビュー系、調査系…）	ルーターに集約
発火文脈がバラバラ	独立スキルのまま
単独で完結、競合しない	独立スキルのまま
description が「全部入り」で曖昧になる	過剰集約。文脈で分割