Claude Codeのスキルdescription｜呼ばれる条件と除外の書き方

Claude Codeは、descriptionと会話文の一致度だけでスキルを選びます。起動語を並べただけのdescriptionでは、Claude Codeのスキルが発火しない場面が残ります。本記事は、言い換え表現・除外条件・近いスキルとの境界をどう書けば発火条件が安定するかを、公式ドキュメントと自社スキルの実例で示します。

01結論：Claude Codeのスキルが発火しないのは、descriptionが起動語の列挙で止まっているから

起動語（コマンド名や機能名そのもの）だけを並べたdescriptionは、ユーザーが違う言い回しで頼んだ瞬間に一致しなくなります。逆に、除外条件を書かないdescriptionは、似た役割の別スキルと範囲が重なり、狙っていない場面でも発火します。直すべき要素は3つです。

• 「何をするか」と「いつ使うか」の両方を書く（公式が明記する必須要素）
• ユーザーが実際に使う言い換え表現を、descriptionかwhen_to_useに足す
• 除外したい場面と、代わりに使うスキル名を1行で添える

Claude Codeは起動時、全スキルのnameとdescriptionだけを読み込みます。1スキルあたりの消費は概ね100トークン程度で、本文（SKILL.mdの中身）は発火した後にしか読み込みません（出典: Anthropic公式）。descriptionは、スキルの中で唯一「常に人の目にも機械の判定にも触れる」場所です。

検証環境は、Claude Code公式（code.claude.com/docs）とAnthropic公式（platform.claude.com/docs）のドキュメントです。いずれも2026-07-28時点の記載です。

02起動語を列挙するだけでは発火条件が安定しない理由

descriptionは、Claude Codeがそのスキルの発火条件を満たすかどうかを判定する唯一の材料です（出典: Claude Code公式）。判定はdescriptionの文章とユーザーの発言全体を読んで行われ、単語の完全一致ではありません。だから、機能名だけを並べたdescriptionは、機能名を言わない依頼に反応できません。

公式ガイドは、descriptionの悪い例として次を挙げています（出典: Anthropic公式）。

description: Helps with documents

description: Processes data

description: Does stuff with files

いずれも「何を」「いつ」が書かれていません。対して公式ドキュメントが挙げる良い例は、PDF処理スキルを題材に「テキストと表の抽出・フォーム入力・文書の結合」という操作を並べたうえで、「PDFを扱うとき、またはPDF・フォーム・文書抽出に言及されたとき」という発動条件を後半に置いています（出典: Anthropic公式）。日本語で書くなら次の形です。

description: PDFファイルからテキストと表を抽出し、フォーム入力や複数ファイルの結合を行う。PDFファイルを扱うとき、またはPDF・フォーム・文書抽出について言及されたときに使う。

前半が「何をするか」、後半が「いつ使うか」です。この2部構成が、descriptionの骨格になります。

descriptionはもう一つ、文体の規約があります。三人称で書くという規約です。「I can help you...」のような一人称は、システムプロンプトに挿入されたときに視点が揺れ、判定の精度を落とします（出典: Anthropic公式）。「You can use this to...」も同様に避ける対象です。

公式チュートリアルの実例も、機能名ではなく状況で誘導しています。gitの差分を要約するスキルのdescriptionは、状況だけで誘導します。「変更点を聞かれたとき」「コミットメッセージが欲しいとき」「差分のレビューを頼まれたとき」の3つです（出典: Claude Code公式）。git diffというコマンド名は使っていません。

03言い換え表現をdescriptionに足して、発火条件を広げる書き方

Claude Codeにはdescriptionとは別に、when_to_useというフロントマター項目があります。トリガーフレーズや依頼例を追加で書く場所で、スキル一覧ではdescriptionの後ろに連結されます（出典: Claude Code公式）。descriptionを短く保ったまま、言い換え表現をここへ足せます。

---
name: expense-check
description: 経費精算の申請内容を、社内規程と照合してチェックする。
when_to_use: |
  「経費精算お願い」「これ経費で落ちる？」「領収書チェックして」と言われたときに使う。
  スキル名を言わない「今月の経費まとめてほしい」のような依頼でも発火する。
---

言い換え表現を足す手順は2ステップです。

1. ユーザーが実際に送ってきそうな言い回しを、口調そのままで3〜5個書き出す
2. 機能名を含む言い回しと、機能名を含まない状況の言い回しを両方入れる

2026-07-28時点でWEBMARKSのVaultに登録されているx-postスキルのdescriptionは、この2種類を両方書いています。「X投稿作って」「ツイート書いて」のような機能名入りの依頼に加え、「今日のツイート案ちょうだい」「これXで一言つぶやきたい」のような機能名なしの依頼も挙げています。後者のような依頼でも発火するとdescription内に明記されています。機能名を知らない読者からの依頼を取りこぼさないための書き方です。

04除外条件で、近いスキルとの発火条件をどう切り分けるか

descriptionが誤って発火しすぎる場合、公式の対処は2つです。descriptionをより具体的にすること、そしてdisable-model-invocation: trueを設定することです（出典: Claude Code公式）。後者は手動起動だけに絞る設定です。

WEBMARKSの本番スキルは、これに加えて三つ目の書き方を使っています。除外したい場面と、代わりに使うスキル名を、description本文の中に文章として明記する方法です。2026-07-28時点で確認できる実例を3つ挙げます。

4行とも構造は同じです。「除外する場面」「代わりのスキル名」「区別する理由」の3点をdescription内に書くと、Claude Codeは似たスキルが並んでも、範囲の広さではなく役割の違いで選べます。

たとえば、議事録を要約するスキルと、商談後の議事録を作るスキルのように対象が重なる2本を、除外条件なしで書いたとします。ユーザーが「昨日のMTGをまとめて」と頼むと、どちらのdescriptionにも一致し、片方だけが選ばれるか、選ばれた方が想定外の形式で出力します。気づくのは、出てきた議事録の項目が期待と違うと感じた時点です。除外条件を1行足すだけで、この重なりは解消します。

05Claude Codeのスキルdescriptionが発火しないかどうかを確認する2つの方法

書いたdescriptionが発火条件として機能しているかは、想像ではなく確認します。

1つ目は対話での確認です。「What skills are available?」とClaudeに聞くと、認識済みのスキル一覧が返ります（出典: Claude Code公式）。/doctorはスキル一覧のコンテキストコストを見積もり、/contextのSkills行は実際に読み込まれた一覧のサイズを表示します。

2つ目はskill-creatorプラグインによる自動評価です。/plugin install skill-creator@claude-plugins-officialで導入します。/reload-pluginsのあとに「evaluate my <skill-name> skill with skill-creator」と頼みます。発火させたいプロンプトと発火させたくないプロンプトの両方を生成し、的中率を測ってdescriptionの修正案まで提案する機能です（出典: Claude Code公式）。

Anthropicは自社の公開スキル6本にこの手法を当てました。5本で発火精度が改善したと報告しています（出典: Anthropic公式ブログ）。

06スキルが呼ばれない条件を放置すると起きる、3つのつまずき

descriptionとwhen_to_useを合わせすぎて切り詰められる

Claude Codeは、descriptionとwhen_to_useの合計を1,536文字で切り詰めます（出典: Claude Code公式）。スキル数が増えて一覧全体の予算を超えると、呼び出し頻度が低いスキルから順にdescriptionが落とされます。一覧の予算は既定で、モデルのコンテキストウィンドウの1%です。

skillListingBudgetFractionを0.02（2%）のように上げると広げられます（出典: Claude Code公式）。落とされる順番を決めるのはdescriptionの長さではなく呼び出し頻度で、使われていないスキルほど先に説明文が一覧から消えます（出典: 同上）。

一人称・二人称で書いて視点がぶれる

「私がPDFを処理します」「あなたはこれでPDFを処理できます」のような一人称・二人称は、システムプロンプトに挿入されたときに文体が揺れます。他のスキルのdescription群からも浮きます（出典: Anthropic公式）。三人称で「〜する」「〜を生成する」と言い切る形に統一します。

name フィールドの制約に違反して、そもそも読み込まれない

nameは64文字以内、小文字・数字とハイフンのみで、anthropicやclaudeという予約語を含められません（出典: Anthropic公式）。この制約に違反すると、descriptionの書き方以前に、スキル自体が一覧に現れません。/skill-nameで直接呼んでも見つからず、Claudeが自動で選ぶ候補にも入りません。「発火しない」ではなく「存在しない」扱いになる、別の失敗です。

除外条件を書く場所と、起動そのものを止める場所は別のフィールドです。混同すると、書いた除外条件が期待どおりに働きません。

07Claude Codeのスキルdescriptionチェックリスト

• descriptionに「何をするか」と「いつ使うか」の両方が入っている
• 三人称で書かれている（「I can」「You can」を使っていない）
• ユーザーが実際に使いそうな言い換え表現を3つ以上、descriptionかwhen_to_useに入れている
• 除外したい場面と、代わりに使うスキル名を1行で書いている
• 近いスキルとの境界を、役割の違いで説明している（範囲の広さだけで分けていない）
• nameが64文字以内・小文字・数字とハイフンのみで、予約語（anthropic・claude）を含まない
• descriptionとwhen_to_useの合計が1,536文字を大きく超えていない
• 「What skills are available?」か/doctorで、発火・非発火を実際に確認した

08FAQ