Claude Codeのスキルが発火しない｜descriptionを直す4層

「スキルは作ったのに、呼ばれないんです」。AIエージェントに定型業務を任せはじめた人から、この相談をよく受けます。

SKILL.mdの中身は丁寧に書いてある。手で名前を打てば動く。それでも、ふつうに話しかけたときには出てこない。原因は中身ではなく、その手前にあるdescriptionのほうにあります。

この記事は、Claude Codeがスキルを選ぶときに何を読んでいるかを確かめ、descriptionのどこに何を書けば呼ばれるようになるかを扱います。素材は公式ドキュメントと、運用中の自社スキルの書き方です。

進行役は3人です。若葉さんが用語の側から、高梨課長が自分の手で直す側から聞き、鈴木さん（本誌監修）が答えます。

01Claude Codeのスキルが発火しないのは、AIエージェントが何を見て選んでいるからですか？

若葉さん

若葉さんの発言

そもそもなんですが、Claudeはどうやって「このスキルを使おう」と決めているんですか。

鈴木さん

鈴木さんの発言

棚に並んだ道具箱の、名札だけを見て決めていると考えると近いです。中身は開けていません。名札に何と書いてあるかで、手が伸びるかどうかが決まります。

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

つまり、選ばれるかどうかが決まる時点で、Claudeが手にしている情報はdescriptionだけです。中身をどれだけ作り込んでも、その内容は判定に参加していません。

判定そのものも、固定のキーワード一致ではありません。YAMLフロントマターのdescriptionに書かれた文章と、ユーザーの発言全体を照合して選びます（出典: Claude Code公式）。文章として読まれるので、同じ単語が無くても意味が近ければ候補に上がります。逆に、単語だけを置いて文として通っていなければ、そこは手がかりになりません。

descriptionは、スキルの中で唯一「常に人の目にも機械の判定にも触れる」場所です。

順番で見ると、descriptionの推敲は読みやすさの調整ではないと分かります。候補に残るかどうかの調整です。中身の推敲が効きはじめるのは、この図の最後の箱に入ってからです。

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

02起動語を並べただけのdescriptionでは、AI社員のスキルがなぜ呼ばれないんですか？

起動語（コマンド名や機能名そのもの）だけを並べた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の骨格になります。

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

コマンド名を知っている人は、そもそも手で呼べます。descriptionが迎えにいく相手は、コマンド名を知らないまま用件だけを言う人です。

03AIエージェントに頼む言い方が変わっても、Claude Codeのスキルが発火しないのを防げますか？

高梨課長

高梨課長の発言

言い回しは人によってばらばらです。全部書き出すことになるんでしょうか。

鈴木さん

鈴木さんの発言

全部は要りません。機能名で呼ぶ言い方と、用件だけを言う言い方。この2種類が混ざっていれば、あいだのゆれは文章として拾われます。

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似たスキルが並ぶとき、AI社員はどちらを選ぶんですか？

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

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

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

たとえば、議事録を要約するスキルと、商談後の議事録を作るスキルのように対象が重なる2本を、除外条件なしで書いたとします。ユーザーが「昨日のMTGをまとめて」と頼むと、どちらのdescriptionにも一致します。気づくのは、出てきた議事録の項目が期待と違うと感じた時点です。

除外条件は、自分のスキルを狭める文ではありません。行き先を書いた案内板です。案内板があるほうが、隣のスキルも本来の依頼を受け取れます。

スキルそのものの分け方や命名の考え方は、AIエージェントのスキル設計｜呼ばれる単位に分ける4つの型にまとめています。

05自動で呼ぶか手で呼ぶか、エージェントのスキル起動はどこで切り替えるんですか？

高梨課長

高梨課長の発言

除外条件を書けば、自動で呼ばれるのを止められる、という理解でよいですか。

鈴木さん

鈴木さんの発言

そこは別のつまみです。除外条件は「どちらの担当か」を書くもので、起動そのものを止める設定は別のフィールドにあります。混ぜると、書いたのに効かないという感じ方になります。

除外条件を書く場所と、起動そのものを止める場所は別のフィールドです。

表は2つの設定を1つずつ説明しますが、実際には同時に効きます。掛け合わせると、表には出てこない区画がひとつ現れます。両方を止めた組み合わせです。ここに入ったスキルは、Claudeからも手からも呼べません。発火しないと悩んでいる原因が、ここに座っていることもあります。

06書いたスキルのdescriptionが効いているかは、生成AIにどう確かめるんですか？

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

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

表の2行は、向きが逆の失敗です。片方だけを直すと、もう片方へ振れます。具体的にすればするほど、拾えていた依頼を落とします。両方向を同じだけ試してから、descriptionを確定させます。

07スキルの発火精度は、AIエージェントに測らせることもできるんですか？

的中率まで出したいときは、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公式ブログ）。

自分で試す言い回しは、どうしても自分が思いつく範囲に寄ります。発火させたくない側のプロンプトまで作らせる意味は、そこにあります。

説明文の発火精度をスキル群まとめて測った記録は、Agent Skillsの発火精度を検証した記事にあります。

08説明文が長すぎると、AI導入したスキルは一覧から落ちるんですか？

Claude Codeは、descriptionとwhen_to_useの合計を1,536文字で切り詰めます（出典: Claude Code公式）。

スキル数が増えて一覧全体の予算を超えると、呼び出し頻度が低いスキルから順にdescriptionが落とされます。一覧の予算は既定で、モデルのコンテキストウィンドウの1%です。skillListingBudgetFractionを0.02（2%）のように上げると広げられます（出典: Claude Code公式）。

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

これは、呼ばれない状態が自分で自分を強める形になっている、ということでもあります。

輪のやっかいなところは、どの地点も不具合には見えないことです。名札は書いてあるし、設定も通っている。ただ順番に回っているだけです。最初の1回を手で呼んでおくと、そこで輪は切れます。

09一人称で書くと、AIエージェントのスキル選びに何が起きるんですか？

descriptionには文体の規約があります。三人称で書く、という規約です。

「私がPDFを処理します」「あなたはこれでPDFを処理できます」のような一人称・二人称は、システムプロンプトに挿入されたときに視点が揺れ、判定の精度を落とします（出典: Anthropic公式）。他のスキルのdescription群からも浮きます。

三人称で「〜する」「〜を生成する」と言い切る形に統一します。日本語なら、主語を省いた言い切りがそのまま三人称になるので、「〜します」を「〜する」に直すだけでも揃います。

10nameの制約に触れると、Claude Codeのスキルはエージェントに見つからず発火しないんですか？

若葉さん

若葉さんの発言

一覧に出てこないときも、descriptionを直せばいいんでしょうか。

鈴木さん

鈴木さんの発言

それは別の失敗です。名前の付け方が規約から外れていると、そもそも棚に並びません。並んでいないものは、名札を書き直しても出てきません。

nameは64文字以内、小文字・数字とハイフンのみで、anthropicやclaudeという予約語を含められません（出典: Anthropic公式）。

この制約に違反すると、descriptionの書き方以前に、スキル自体が一覧に現れません。名前を直接打っても見つからず、Claudeが自動で選ぶ候補にも入りません。「発火しない」ではなく「存在しない」扱いになる、別の失敗です。

切り分けは先に済ませます。「What skills are available?」で一覧に出るかを見て、出ていればdescriptionの言い回しの問題、出ていなければnameか設定の問題です。順番を逆にすると、直しても変わらない作業を続けることになります。

フロントマターの各項目の書き方そのものは、SKILL.mdの書き方、フロントマターから参照ファイル分割までで扱っています。

11AI活用の現場で、スキルのdescriptionはどの順番で直していけばいいんですか？

ここまでの要素を、積む順番に並べ直します。

下の層が欠けたまま上を足しても、効きません。言い換えをいくつ並べても、何をするスキルなのかが書かれていなければ、そもそも比べる土俵に乗らないからです。逆に、土台さえあれば、上の層は運用しながら足していけます。

自分のdescriptionを見直すときは、下から順に読み上げて、どこで手が止まるかを見ます。

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

12よくある質問

13まとめ｜今日やる3つのこと

呼ばれるかどうかは、中身ではなく名札で決まっていました。名札には積む順番があり、下の層が欠けたままだと、上をいくら足しても効きません。そして、書いた事実は呼ばれた事実の代わりになりません。