【Claude Codeスキル入門 第3回】発動する説明を書く ― descriptionの2つの問い、頼み方の言い回し、言い回しを変えて試す、似たスキルの分け方と名前

「スキルを作ったのに、Claude がまったく使ってくれません。『検証して』と頼んでも、スキルを使わずに自分で動き出します」
「逆に、使ってほしくない場面でスキルが発動してしまいます。どこを直せばよいのでしょう」

第2回（SKILL.mdを書く）では、SKILL.md の置き場所と書き方を見ました。ところが、スキルを作っただけでは、Claude が使うとは限りません。スキルを使うかどうかを決める手がかりは、SKILL.md の frontmatter にある description（説明）だけだからです。

第3回では、description が答える2つの問い、発動しない説明と発動する説明の違い、頼み方の言い回しを入れる理由、言い回しを変えて試す方法、似たスキルの分け方と名前の付け方を扱います。冒頭の2つの相談は、どちらも description の書き方で直せます。

---

説明は2つの問いに答える

Claude は、依頼の意味と、全スキルの description の意味を照らし合わせ、合うものを使います。Academy のレッスン2・6は、これを「セマンティックマッチング」と呼びます。この連載では、依頼が description と合うことを「一致する」、Claude がスキルを使うと決めることを「発動する」と呼びます。

良い description は、2つの問いに答えます。

• スキルは何をするのか
• Claude はいつ使うべきか

「ドキュメントを手伝う」では、人が聞いても何をすればよいか分かりません。公式も、何をするかといつ使うかの両方を書くよう勧めています。Platform のベストプラクティスは、「description は、スキルの発見（discovery）を可能にするフィールドで、スキルが何をするかと、いつ使うかの両方を含めるべき」と書いています。同じ文書は、description を三人称で書くよう勧めています（description はシステムプロンプトに入るので、視点が混ざると発見の問題を起こすことがある、という理由です。「Excel ファイルを処理してレポートを作る」は良く、「Excel ファイルの処理をお手伝いできます」は避ける、という例が挙がっています）。

• 依頼が description と一致すると、Claude が発動する
• 良い description は「何をするか」「いつ使うか」に答える
• 日本語では「〜を行う。〜のときに使う」の形にそろえる（筆者の書き方で、公式の推奨ではない）

---

発動しない説明と発動する説明

• 発動しにくい例：「Ansible を手伝う」。何をするかも、いつ使うかも分からない
• 発動する例（ansible-verify）：何をするか（lint・構文確認・stg の差分確認）、頼み方（「検証して」など）、使う場面（playbook を編集し終えたとき）を書く
• 筆者の実例（share-deck）：作業の流れ（案の確認から納品まで）と、「資料の第N回を作って」のような頼み方を description に書いている（要約）

# 発動しにくい
description: Ansible を手伝う

# 発動する（ansible-verify）
description: Ansible の playbook・role を変更した後の検証
  （ansible-lint、構文確認、stg への --check --diff）を行う。
  「検証して」「lint 通る？」「stg で差分を見て」と頼まれたとき、
  または playbook を編集し終えたときに使う。

補足：出典は https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices と https://code.claude.com/docs/ja/skills です。公式は、具体的な言葉で、何をするかと使う場面の両方を書くよう勧めています。share-deck の例は、構成と考え方だけの紹介です。第6回の「SKILL.md（案）」では、同じ文言を1行で書きます。

Platform のベストプラクティスは、「具体的に、重要な語（key terms）を入れる。何をするかと、使うきっかけ・文脈（specific triggers/contexts）の両方を書く」と書いています。

---

普段の言い回しを入れる

• 頼み方の言葉を入れる：公式は、ユーザーが自然に言うキーワードを description に入れるよう勧める。Academy のコースも、実際の言い方に合うフレーズを足すとある
• 日本語で頼むなら日本語で書く：「検証して」「lint 通る？」「stg で差分を見て」。日本語の description で発動するかは、公式に記載が見つからず、下の「筆者が試したら」で確かめた
• 英語と日本語を両方：lint・check・diff と、検証・確認・差分（筆者の書き方）
• 場面も書く：「playbook を編集し終えたとき」のように、頼まれる前の場面も入れる
• 発動してほしくない依頼も考える：「本番に流して」で発動させない。検証スキルに本番へ流す言葉を入れない

補足：出典は https://code.claude.com/docs/ja/skills （Troubleshooting）と、Academy のレッスン6です。

公式のトラブルシュート「Skill not triggering」（スキルが発動しない）は、最初に「description に、ユーザーが自然に言うキーワードが入っているか確かめる」ことを挙げます。Academy のレッスン6も、「ユーザーが実際に言いそうなトリガーフレーズを足す」ことを勧めています。公式には、description に足せる when_to_use というフィールドもあり、「頼まれ方のフレーズや、依頼の例」を書く場所とされています（スキルの一覧に載るときは、description と合わせて1,536字で切り詰められます）。

description が長すぎると、一覧で切られることにも注意が必要です。公式は、スキルが多いと、Claude Code が一覧の文字数の予算に収めるため、いくつかの description を切り詰めると書いています。その予算は、モデルのコンテキストウィンドウの1%です。あふれたときは、呼び出す回数の少ないスキルからdescription が落ち、よく使うスキルは全文が残ります。落とされると、Claude が依頼と照らし合わせるためのキーワードが消えます（スキルの名前は、いつも全部が一覧に載ります）。だから、description は短く、大事な使いどころを先頭に書きます。

日本語の description について、Platform のベストプラクティス・公式の Skills のページ・仕様（agentskills.io）・Academy のコースを調べましたが、description の言語についての記述は見つかりませんでした。

---

言い回しを変えて試す

1つのスキルを、いくつかの頼み方で試します。表のように、発動してほしい頼み方と、発動してほしくない頼み方の両方を試します。

頼み方	期待	見ること
「検証して」	発動する	verify.sh を実行したか
「lint 通る？」	発動する	同上
「stg で差分を見て」	発動する	同上
「本番に出す前に確かめて」	発動する	確かめるだけで、本実行しないか
「roles/ntp の説明を書いて」	発動しない	別の作業なので使われないか
「本番に流して」	発動しない	prod は ask で確認が出る（実践入門 第6回「Ansibleの作業での設定例（筆者の例）」）

補足：1つのスキルを、表のようにいくつかの頼み方で試し、発動しなかった言い回しは description に足します。発動してほしくない依頼でも試します。表の結果は、下の「筆者が試したら」にあります。出典は、Academy のレッスン6と https://code.claude.com/docs/ja/skills です。

公式のトラブルシュートは、発動しないときの手順として、次の順を挙げています。

1. description に、ユーザーが自然に言うキーワードが入っているか確かめる
2. 「利用可能なスキルは？」（What skills are available?）で、スキルが一覧に出るか確かめる
3. description に近づけるように、言い方を変えて頼んでみる
4. スキルが人からも呼べるなら、/スキル名 で直接呼ぶ
5. /スキル名 も認識されないなら、Claude Code がスキルの名前を受け付けなかったのではないかを確かめる

Academy のレッスン6は、「このプロファイリングを手伝って」「これはなぜ遅いの？」「これを速くして」のように、言い回しのバリエーションでテストするよう勧めています。

もっと体系的に試したいときの公式の勧めは、2つあります。Platform のベストプラクティスは、「長い文書を書く前に、評価（evaluation）を作る」ことを勧め、チェックリストには「少なくとも3つの評価を作る」とあります。ただし、「これらの評価を走らせる組み込みの方法は、今のところ無い。自分で評価の仕組みを作る」とも書いています。公式の Skills のページには、プラグインに入れたスキルなら、現実的なプロンプトで何回発動するかを claude plugin eval で測れる、という記述があります。この連載では、手で言い回しを変えて試す方法を使います。

筆者が試したら

CLI の claude -p（非対話。Claude Code 2.1.289、モードは「手動」、モデルは既定）で、第10回の演習の手順3・4（「手順3：言い回しを変えて発動させる」「手順4：発動しなかった言い回しを足す」）を試した結果です。この演習では、ansible-verify の description は Claude に作らせたもので、上の例の「検証して」「lint 通る？」を入れたものとは文言が違います。

description: ansible-lint、構文チェック、stg への --check --diff を順に実行し、変更内容を検証する。playbook・role・inventory などの Ansible の変更を作ったあと、本実行や prod への実行を提案する前に使う。

-p は毎回新しいセッションなので、1つの頼み方ごとに新しいセッションで1回ずつ試しました（同じ頼み方を繰り返して、結果が毎回同じかは確かめていません。「本番に出す前に確かめて」「roles/ntp の説明を書いて」は試していません）。

頼み方	結果	起きたこと
「検証して」	発動した	lint・構文確認・差分確認を順に実行した
「lint 通る？」	発動しなかった	スキルを使わず、ansible-lint を直接実行して「はい、通ります」と答えた
「stg で差分を見て」	発動した	上と同じ3段階を実行した
「本番に流して」	発動した（表の期待と違う）	stg の3段階を実行して止まり、「stg を直してから確認し直すか、了承があれば prod に --check --diff を流す」と2択を返した。本番には流さなかった

• 日本語の description でも、「検証して」「stg で差分を見て」では発動しました
• 「lint 通る？」は、description に lint だけを頼む言い回しが無かったので、足す前は発動しませんでした。表のとおり「言い回しを足す」直し方が効く例です
• 「本番に流して」は、表では「発動しない」と期待しましたが、発動しました。description の「本実行や prod への実行を提案する前に使う」に一致したと筆者は見ています。ただし、止まって本番には流さなかったので、「発動してほしくない依頼」は description の文言しだいで発動することと、スキルの発動と、実行の可否は別であることが分かります
• そこで description の末尾に「「lint 通る？」「構文を確かめて」のように、lint や構文の確認だけを頼まれたときにも使う。」を足して、新しいセッションで「lint 通る？」と頼むと、発動しました（3段階とも実行）

この結果の詳しい経緯は、第10回の手順3・4で扱います。

---

似たスキルを分ける・名前を具体的に

• 説明が似すぎないようにする：似た description があると、違うスキルが使われる。対象と場面で区別する
• 名前は具体的に：review だけにせず ansible-review、pptx-review のように対象を付ける。helper・utils のような曖昧な名前は避ける（Platform のベストプラクティス）
• verify だけは使わない：公式の組み込みに /verify があり、同名のスキルを置くと置き換える。コミット前に実行される条件にもなる。だから ansible-verify
• 同じ名前は優先順位で決まる：Enterprise が個人に、個人がプロジェクトに優先する（公式）。詳しくは第8回の「優先順位と名前の付け方」
• 発動しすぎるとき：description をより具体的にする。自動では使わせたくないなら disable-model-invocation: true

補足：出典は https://code.claude.com/docs/ja/skills と https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices です。自分の verify スキルが組み込みを置き換え、コミットの直前に実行する指示の対象にもなる仕組みは、Claude Code v2.1.286 以降です（第8回の「優先順位と名前の付け方」と同じ）。

名前について、Platform のベストプラクティスの勧めを足します。動名詞（verb + -ing）の名前（processing-pdfs、analyzing-spreadsheets、managing-databases）を勧め、受け入れられる別の形として、名詞句（pdf-processing）や動作の形（process-pdfs）を挙げています。避けるのは、helper・utils・tools のような曖昧な名前です。ansible-verify は、対象と動作を並べた名詞句の形です。また、name に使えるのは小文字・数字・ハイフンだけ（最大64字）で、Platform は anthropic・claude の語を含む名前を禁じています（第2回の「frontmatter のフィールド」）。

組み込みの /verify との関係は、公式の Skills のページに書かれています。

• 組み込み（同梱）のスキルの1つに /verify があります。公式の説明は「プロジェクトのアプリをビルドして動かし、結果を観察して、コードの変更が意図どおりかを確かめる。テストや型チェックだけに頼らない」です。/verify は、人が呼んだときだけ動きます
• 同名のスキルを、個人・プロジェクトなどの場所に置くと、自分のスキルが組み込みのコマンドを置き換えます（組み込みの別名は置き換わりません）。/verify を自分のスキルで置き換えたい場合は、これで動きますが、意図せず置き換えないよう、verify だけの名前は避けます
• セッションの開始時に verify か simplify という名前のスキルがあると、Claude Code のコミットの指示が、Claude に各コミットの直前に実行するよう伝えます（ドキュメントやテストだけの変更を除く）。Claude Code v2.1.286 以降です。この対象になるのは、個人・プロジェクト・追加ディレクトリ・組織の場所、または .claude/commands/ のファイルから読み込まれたスキルで、組み込みの /verify・/simplify、プラグインのスキル、claude.ai のアカウントのスキルは対象になりません

つまり、「検証して」と頼まれたときだけ動かしたい ansible-verify を、verify という名前にしてしまうと、コミットのたびに動くことになりかねません。名前は対象まで含めて付けます。

同じ名前のスキルが複数あるときの公式の規則は、次のとおりです。

同じ名前が	どちらが動くか
Enterprise・個人・プロジェクトのうちの2つ	Enterprise が個人に、個人がプロジェクトに優先する。deploy が ~/.claude/skills/ とプロジェクトの .claude/skills/ の両方にあれば、/deploy は個人のものを動かす
プラグインのスキルと、上の場所のスキル	両方が読み込まれる。プラグインのスキルは /plugin名:スキル名 と名前空間が付くため
入れ子（サブディレクトリ）のスキルと、ルートのスキル	両方が読み込まれる

発動しすぎるときの公式の直し方（Skill triggers too often）は、次の2つです。

1. description をより具体的にする
2. 手動でだけ使いたいなら、disable-model-invocation: true を足す

disable-model-invocation: true にすると、公式の表では、description は Claude のコンテキストに載らず、人が呼んだときに全文が読み込まれます（Claude は自分では呼べません）。公式の説明のとおり、副作用のある作業や、実行のタイミングを自分で決めたい作業に向きます。

---

考えてみよう

1. 自分のスキルの description を、「何をするか」「いつ使うか」の2つの問いに分けて書き出してください。どちらかが空なら、どう足しますか
2. そのスキルを呼びそうな普段の言い回しを3つ、発動してほしくない言い回しを1つ書いてください。それぞれ、発動するか試す前に予想しておくと、結果が比べられます
3. 「review」という名前のスキルが2つあって、どちらも似た description です。どう直しますか。「verify」という名前を付けるときは、何に注意しますか

ヒント：1は「説明は2つの問いに答える」の節、2は「普段の言い回しを入れる」と「言い回しを変えて試す」の節、3は「似たスキルを分ける・名前を具体的に」の節を見直してください。

---

まとめ

• Claude は、依頼の意味と全スキルの description の意味を照らし合わせ、合うものを発動する。スキルを使うかどうかの手がかりは description だけ
• 良い description は、何をするかといつ使うかの2つに答える。三人称で、具体的に。日本語は「〜を行う。〜と頼まれたときに使う」の形にそろえる（筆者の書き方）
• ユーザーが自然に言う言い回しを入れる。足りなければ足す。日本語の description でも、筆者の試しでは「検証して」で発動した（description の言語についての公式の記述は見つかっていない）
• 言い回しを変えて試す。発動してほしい頼み方も、してほしくない頼み方も。「lint 通る？」は足すまで発動せず、「本番に流して」は発動して止まった。発動と、実行の可否は別
• 名前は対象まで含めて具体的に（ansible-verify）。verify だけにすると組み込みの /verify を置き換え、コミットの直前に動く条件にもなる（v2.1.286 以降）
• 発動しすぎるときは、description を具体的に。手動だけなら disable-model-invocation: true。description が長すぎると、一覧で切られる

次回は、スキルを複数のファイルに分ける方法を扱います。段階的開示、フォルダーの構成、スクリプトは読まずに実行させること、allowed-tools との関係です。

---

連載「Claude Codeスキル入門」全12回

全回の目次と、読む順番・目的別の読み方は、Claude Codeスキル入門の入口のページにまとめています。

1. スキルとは何か
2. SKILL.mdを書く
3. 発動する説明を書く（この記事）
4. 複数のファイルに分ける
5. スクリプトとallowed-tools
6. 検証スキルを作る（前編）
7. 検証スキルを作る（後編）
8. Gitでチームに共有する
9. うまく動かないとき
10. 演習（前編）：作る・確かめる・発動させる
11. 演習（中編）：分ける・事前承認
12. 演習（後編）：共有と振り返り