Claude Code の Skills 機能を3週間運用したうえでの設計指針を、実際に詰まったポイントとセットで整理する。Skills は1ディレクトリ1ファイル（SKILL.md）という最小構成ながら、description の書き方と Progressive Disclosure の理解次第でトリガー精度とトークン消費が大きく変わる。MCP サーバが「新しい能力」を付与するのに対し、Skill は「振る舞い（指示）」を渡す位置付けで、両者は補完関係にある。本稿では実機での試行錯誤を踏まえ、効く Skill 設計の要点をまとめる。
Skill の最小構成と MCP との役割分担
Skill は1つのディレクトリに SKILL.md を1つ置くだけのフォーマットだ。YAML フロントマターで name / description を宣言し、その下に Markdown で Claude が従う指示を書く。それ以上の構成要素はない。
外部ツールとの違いは明確で、MCP サーバが「新しい能力（API 呼び出し等）」を Claude に与えるのに対し、Skill は「どう振る舞ってほしいか」の指示を渡す。能力の追加と振る舞いの定義は別レイヤーなので、両者を組み合わせて使うのが現実的だ。
description の具体化でトリガー精度が30%→80%超に
筆者が最初に書いた Skill の description は「TypeScript のベストプラクティス」とだけ書かれた抽象的なものだった。結果、Claude はほぼトリガーしてくれず、Skill 自体の存在意義が成立しなかった。
書き方を「具体的な発火条件」に変えた瞬間、トリガー精度は体感30%から80%以上に跳ね上がった。例として「npm test コマンドが実行された時」「stripe を import しているファイルを編集する時」のような形だ。description の1行は、Skill 全体で最も投資対効果が高い部分だと言える。
Progressive Disclosure：本文は500トークン以下、参照は別ファイル
Skills の挙動の核心は「段階的開示」にある。Claude はまず全 Skill の name / description だけをスキャンし（1Skill あたり約100トークン）、関連すると判断したものだけ本文を読み込む。本文の推奨上限は5kトークン以下だ。
この前提が分かると、設計方針が変わる。本文に詳細な参照テーブルを全部詰め込むのは悪手で、本文は500トークン以下に絞り、長い参照は同ディレクトリの別ファイルへリンクで分離する。筆者の手元の Skill 群でこの圧縮を行った結果、トータルのコンテキスト消費量が47%減った。長時間タスクではこの差が実コストに直結する。
実運用で毎日効いている3つの Skill 例
参考までに、筆者が業務で毎日使っている Skill を3つ挙げる。中身は社内ツール依存だが、設計の考え方は転用可能だ。
1つ目は「PR レビューのチェックリスト」。description は「git diff を表示した直後、または pr review が要求された時」。本文には変数命名 / エラーハンドリング / テスト追加 / 型注釈など、観点を7項目だけ箇条書きで置く。
2つ目は「ライブラリ更新時の互換性チェック」。description は「package.json を編集する時、または npm update 系コマンドの直後」。breaking change の照会先と確認手順だけを書いている。
3つ目は「日次レポート生成」。description は「daily レポート、もしくは進捗まとめが要求された時」。テンプレと参照ファイルのパスだけを書いている。3つとも5kトークン以内、本文は1KB 以下に収まっている。
ハマりやすい3つの落とし穴
筆者が通った失敗パターンを共有しておく。1つ目は本文に詳細な API 仕様を全部詰め込み、SKILL.md が12KB に膨らんだケース。毎回コンテキストの大半を Skill が食う事態になり、リンクで参照を分離して解消した。
2つ目はテスト用に API キーを SKILL.md に書いた件。Skill は複数人で共有・公開される可能性があるため、秘密情報は環境変数かシークレットマネージャ経由が原則だ。これは作業上の都合に関わらず守るべき線で、最初から徹底したほうがいい。
3つ目は description が抽象的で Claude が拾わないケース。これは前述の通り、具体名詞と動詞で発火条件を書き直すだけで改善する。
効果測定の3指標：トリガー率・トークン削減・体感
Skill が実際に効いているかは、3つの方法で測れる。方法1はトリガー率で、100回タスクを回したうち Skill が発火した回数をカウントする。意図したタスクで70%以上、無関係なタスクで5%以下が目安だ。この水準を満たさない場合は description の再設計が必要になる。
方法2はトークン削減量。Skill なしで同じタスクを回した時のトークン消費と比較し、毎回プロンプトに同じ説明を書く必要がなくなった分を算出する。筆者の手元では平均で23〜35%程度の削減が見えている。
方法3は体感時間。Skill が効いている時は Claude の初動が「何を聞き返すか」フェーズを飛ばし、いきなり実装に入る。この体感が出ない場合は、description の発火条件と本文の指示の整合性を見直すサインだ。
description で避けたい抽象ワード
最後に、description に書きがちでトリガー精度を下げる抽象ワードを挙げておく。「ベストプラクティス」「効率化」「最適化」「自動化」はいずれも対象が広すぎて、Claude 側で「今このタスクに該当するか」の判定が立たない。
代わりに、具体名詞と動詞を組み合わせる。「React コンポーネントを作成する時」「API 呼び出しのエラーハンドリングを書く時」のように、画像が浮かぶレベルの具体性を持たせることで、Claude 側の判断材料として機能する。description の1行を書き直すだけでトリガー精度が変わるため、まずここから手を入れるのが効率的だ。
推奨アクション
- 既存 Skill の description を「具体的な発火条件」に書き直す（最も投資対効果が高い）
- 本文を500トークン以下に圧縮し、長い参照は同ディレクトリの別ファイルへリンクで分離
- API キーなどの秘密情報が
SKILL.mdに混入していないか確認し、環境変数かシークレットマネージャに移す - トリガー率・トークン削減量・体感時間の3指標で運用後の効果を測定
Skills は1ディレクトリ・1ファイルの最小構成ゆえに、設計の良し悪しがそのまま挙動に出る機能だ。description の具体化と Progressive Disclosure の理解という2点だけでも、運用上の手応えはかなり変わってくる。
