description の書き方（ディスクリプション）

スキルを自作し始めた人向け

自作スキルが「いざという時に呼ばれない」。SKILL.md を書いて保存したのに、Claude Code が肝心な場面で素通りする。原因の多くは frontmatter の description 欄の中身です。ここは飾りの説明文ではなく、Claude が「このスキル、今使うべき？」を判断するための唯一の手がかりになっています。

逆に言うと、ここさえ整えれば自動で発火する確率がぐっと上がります。私はこの欄を「ただの紹介文」だと思っていた時期があって、ずいぶん損をしました。

噛み砕くと

description は、新しい職場に貼り出された「この道具、どんな時に使うか」の貼り紙みたいなものです。棚に道具（スキル本体）があっても、貼り紙が無ければ誰もいつ手に取るか分かりません。

Claude はこの貼り紙を常に視界に入れていて、ユーザーが何か頼んできた瞬間に「あ、これはあの道具の出番だ」と判断します。だから貼り紙が空欄だったり、中身が薄かったりすると、道具は棚で眠ったままになります。

ここが地味だけど効きます。

大事な前提：description は「常に見えている」だけで本体は見えていない

公式の表によると、ふつうの状態だと description は「always in context（常に視界の中）」、本体の指示は「呼ばれて初めて読み込まれる」と区別されています。

つまり Claude は、スキルの中身を知らないまま description の1〜2文だけで「使う／使わない」を決めている。中身がどれだけ良くても、この1〜2文がズレていたら永遠に呼ばれません。だからここの書き方が全てを握ります。

ひとつ例外があります。設定欄に disable-model-invocation: true と書かれているスキルは、description そのものが Claude の視界に入りません。これは「Claude に勝手に使われたくない」スキルがわざと自動利用を切っている状態で、description をどれだけ整えても自動では呼ばれません。手動で /スキル名 と打って使う前提のスキルです。

書き方：①何をするか＋②いつ使うか、を1文で並べる

良い description には決まった型があります。前半に「このスキルが何をするか」、後半に「どんな時に使うか」。この2点をセットで書くだけです。

公式が手本として載せているスキルの説明文を、英文のまま2つ引きます。日本語に直すと細かいニュアンスが落ちるので、構造を見てほしいのでそのまま貼ります。

description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.

description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.

どちらも前半が動詞で始まる「何をするか」、後半が Use when ... で始まる「いつ使うか」。しかも後半には、ユーザーが自然に口にしそうな言い回しが具体的に並んでいます。「変更点を聞く」「新しいプロジェクトを見て回る」みたいに。

ここが核心です。

もう1つ大事なのが「大事な用途を先頭に書く（key use case first）」というルール。公式の表には、description と when_to_use を合わせた文章が 1,536 文字で切られると明記されています。後ろに置いた大事な一言が、切られて消えることがある。だから一番呼んでほしい場面を真っ先に書きます。

なお description を書かなかった場合は、本文Markdownの最初の段落が代わりに使われます。ただこれは運任せなので、自分で1〜2文書いたほうが確実です。

「料理ブログのレシピ整形スキル」を例に、実際の手順を見る

料理ブログを運営していて、レシピの下書きを「材料」「手順」「コツ」の3見出しに整える自作スキルを作ったとします。名前は recipe-format。本体の指示はバッチリ書けている前提で、description 欄だけを詰めていきます。

ステップ1: まず「名前を言い換えただけ」の悪い例から始まる

最初に私がよくやる失敗がこれです。

---
name: recipe-format
description: レシピ整形スキル
---

一見ちゃんと書けてそうに見えます。でもこれは「何をするか」も「いつ使うか」も入っていない。スキル名を言い換えただけです。Claude はこの1行を見ても、いつ呼べばいいのか判断できません。

ステップ2: 料理ブログを開いて「このレシピ整えて」と頼んでみる

下書きのレシピファイルを開いた状態で、Claude Code にこう打ちます。

$ claude
> この豚の角煮のレシピ、整えて

ここで初心者がやりがちな勘違いがあります。「整形」とファイルに書いたんだから「整えて」でも通じるだろう、と思い込むこと。Claude は description に書かれた言葉とユーザーの言葉を照らし合わせます。「整形」しか書いていないと「整えて」と噛み合わず、スキルが棚で眠ったまま、ふつうの回答が返ってきます。

ステップ3: 「何をするか＋いつ使うか」に書き直す

公式の手本と同じ型に直します。

---
name: recipe-format
description: レシピの下書きを「材料」「手順」「コツ」の3見出しに整える。
  レシピを整えたい、材料と手順に分けたい、分量をそろえたいと言われた時に使う。
---

前半が「何をするか（3見出しに整える）」、後半が「いつ使うか」。しかも後半には、料理ブロガーが自然に言いそうな言葉を3つ並べました。「整えて」「材料と手順に分けて」「分量そろえて」です。

ステップ4: もう一度「このレシピ整えて」と頼む

同じ頼みごとをもう一度。

> この豚の角煮のレシピ、整えて

今度は description の中に「整えたい」という言葉が入っているので、Claude が「あ、recipe-format の出番だ」と判断して自動で発火します。材料・手順・コツの3見出しに整った下書きが返ってきます。書き直したのは1行だけ。なのに挙動がはっきり変わります。

ステップ5: 一番呼んでほしい用途を先頭に寄せる

もし他にもスキルをたくさん入れているなら、description は予算内に収まるよう短縮され、後ろのキーワードが落ちることがあります。だから一番多い用途を先頭に。レシピ整形なら「3見出しに整える」を真っ先に置く、という具合です。

ステップ6: 逆に呼ばれすぎる時は文章を具体的にする

「整えて」だけだと、レシピと関係ない文章整理まで拾ってしまうことがあります。その時は description をより具体的に。「レシピの下書きを」と対象を限定する一言を足すと、関係ない場面では発火しなくなります。これも公式が案内している直し方です。

つまり description は何をしてくれるのか

• やってくれる: ユーザーの頼みごとと照らし合わせて、Claude が「このスキルを今使うべきか」を自動で判断する材料になる
• やってくれない: スキル本体の指示そのものは持たない。あくまで「何を・いつ」の1〜2文だけ。中身は呼ばれて初めて読まれる
• 意味が薄い場面: 自分で毎回 /recipe-format と手で打って呼ぶと決めているなら、自動発火の判断材料としての出番は減る（それでも一覧表示のために書いておくと親切）

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 料理ブログのレシピ整形スキルが呼ばれない時

豚の角煮や肉じゃがの下書きを整えたいのに、「整えて」と打っても普通の返事しか来ない。description を見ると「レシピ整形スキル」とだけ。ここに「整えたい、材料と手順に分けたい、分量そろえたいと言われた時に使う」を足すだけで、翌日から「このレシピ整えて」が一発で通るようになります。語ズレが原因の典型例です。

シナリオ2: 家計簿アプリの開発で、コード確認スキルが過剰に出る時

家計簿アプリを作っていて、変更点をまとめるスキルを入れたとします。ところが雑談しただけで毎回発火してうるさい。これは description が漠然としているサイン。「変更を確認する」みたいな広い言い方をやめて、「保存していない変更点をまとめて、危なそうな所を指摘する」のように対象と動作を絞ると、関係ない場面では黙るようになります。

シナリオ3: スキルを10個以上入れていて、たまに使うスキルが急に発火しなくなる時

趣味のレシピサイトに整形・校正・画像説明文・SEO見出しなど、スキルを大量に積んだとします。すると説明文が予算内に収まるよう短縮され、後ろに書いたキーワードが消えて発火しなくなることがある。/doctor で予算があふれていないか確認しつつ、各スキルの description で一番大事な用途を先頭に寄せておくと、消えにくくなります。

初心者が踏みやすい落とし穴

• ユーザーが自然に言う言葉が入っていない。発火しない原因No.1。公式のTroubleshootingも筆頭にこれを挙げています。「整形」と書いて読者は「整えて」と言う、この語ズレで呼ばれません。
• 「何をするか」だけ書いて「いつ使うか」を書かない。前半だけでは Claude が発火タイミングを決められません。後半の「Use when〜（いつ使うか）」を必ずセットで。
• 長く詳しく書けば確実に発火すると思い込む。description と when_to_use の合算は 1,536 文字で切られます。長文の末尾に置いた大事な一言ほど消えやすい。
• 大事な用途を後ろに置いてしまう。スキルが多いと説明文がさらに短縮されます。一番呼んでほしい場面は必ず先頭に。
• when_to_use に逃がせば上限を回避できると思う。when_to_use も合算で同じ 1,536 文字にカウントされます。別欄に移しても総量は変わりません。
• スキル名を言い換えただけで満足する。「レシピ整形スキル」のような名前の焼き直しは、Claude にとって判断材料ゼロと同じです。
• 発火しすぎを放置する。漠然とした説明文は無関係な場面まで拾います。対象を限定する一言を足して具体的にします。
• disable-model-invocation: true が入っているのに自動発火しないと悩む。この設定が入ったスキルは description が Claude の視界に入りません。手動で /スキル名 と打つ前提のスキルなので、自動で呼ばせたいならこの行を消します。

書き方

---
name: recipe-format
description: レシピの下書きを「材料」「手順」「コツ」の3見出しに整える。レシピを整えたい、材料と手順に分けたいと言われた時に使う。
---

やってみるとこうなる

入力

description: レシピ整形スキル

出力例

description: レシピの下書きを「材料」「手順」「コツ」の3見出しに整える。レシピを整えたい、材料と手順に分けたい、分量をそろえたいと言われた時に使う。（前半に「何をするか」、後半に「いつ使うか」を置き、ユーザーが自然に言う言葉をトリガーとして並べる。これで『このレシピ整えて』で自動発火する）

関連項目

• YAML Frontmatter（ヤムル・フロントマター）
• Skills（スキルズ）
• Progressive Disclosure（プログレッシブ・ディスクロージャー）
• skill-creator（スキルクリエイター）

公式ドキュメント

https://code.claude.com/docs/en/skills