呼ばれる説明文の書き方

前のレッスンで、繰り返している仕事の中からスキルの候補を選びました。ここからは、選んだ仕事を実際にスキルとして動かすための、いちばん最初のつまずきどころを扱います。

スキルの本文がどれだけ丁寧に書けていても、descriptionが弱いと、そのスキルは一度も呼ばれません。 Claude Codeの公式ドキュメントは、descriptionを「スキルが何をするか、いつ使うべきか。Claudeはこれを使って、そのスキルを適用するかどうかを判断する」フィールドだと説明しています。名前も本文も正しいのに、この1つのフィールドだけが原因で「作ったのに動かない」が起きます。

何をするか、いつ使うべきか

良いdescriptionは、2つの問いに答えます。何をするスキルかと、どんな場面で使うべきかです。この2つが揃っていないと、Claudeは似たような話題が出たときに、このスキルを候補として思い出せません。

Claude Codeのフロントマターには、descriptionを補う when_to_use という任意のフィールドもあります。公式ドキュメントによれば、descriptionとwhen_to_useを合わせた文章は、スキル一覧の表示上1,536字で切り詰められ、重要な使いどころほど先に書くことが推奨されています。長く書けるからといって説明を後ろに引き延ばすのではなく、いちばん典型的な使いどころを最初の1文に置くのが要点です。

descriptionが省略されたときの挙動

descriptionは推奨フィールドであって必須ではありません。ただし省略した場合、Claude CodeはSKILL.md本文の最初の空行でない行を、そのままdescriptionとして扱います。多くの場合、本文の書き出しはdescriptionとして最適化されていないため、結果として呼ばれにくいスキルになります。descriptionは省略せず、自分で書くのが安全です。

呼ばれないときに、まず疑う場所

スキルを作ったのに一度も呼ばれない場合、原因の多くはdescriptionにあります。Claude Codeでは/skillsコマンドでスキルの一覧を確認でき、descriptionが実際の頼み方とどれだけ噛み合っているかを見直す起点になります。

自分で読み返すだけでは、どこが弱いのか気づきにくいこともあります。そんなときは、Claude自身に読ませて指摘させる方法があります。

このSKILL.mdのdescriptionを読んで、「何をするスキルか」と「いつ使うべきか」の2つにちゃんと答えているか教えてください。実際に頼みそうな言い回しを3つ挙げて、それぞれで呼ばれそうか判定してください。

descriptionを直したら、想定している頼み方を実際に打ってみて、呼ばれるかどうかを確かめる。この往復が、いちばん確実な調整方法です。

やってみよう

演習1：自分のdescriptionを2問で採点する

前のレッスンで書き出したスキル候補について、descriptionの下書きを1つ書いてください。「何をするか」に答えているか、「いつ使うべきか」に答えているかを、それぞれ○×で採点してみましょう。

演習2：実際の頼み方でテストする

そのスキルを使ってほしい場面を3つ想像し、自分ならどう頼むかを実際の言い回しで書き出してください。descriptionの中に、その言い回しに近い言葉が含まれているかを確認しましょう。

今日のまとめ

3行で振り返ります。

• descriptionは「何をするか」と「いつ使うべきか」の2つに答える文で、Claudeはこれを使って呼ぶかどうかを判断する
• descriptionを省略すると本文の最初の行がそのまま使われ、呼ばれにくくなる。省略せず自分で書く
• スキルが呼ばれないときは、まずdescriptionが実際の頼み方の言い回しと噛み合っているかを疑う

次のレッスンでは、SKILL.mdの中身をどう組み立てるか、資料やスクリプトをいつファイルに分けるかを扱います。