説明文の書き方

第02章で見たとおり、呼ばれるかどうかは説明文で決まります。この章はその書き方を、僕の現役34本で実際に使っている型で仕上げます。入れるものは3つ。何をするか、いつ使うか、そして現場の言い回しです。

直す前と直した後

まず、悪い説明文と良い説明文を並べます。中身の手順はまったく同じスキルです。

直す前：
description: 文章をきれいに整えるスキル。

直した後：
description: 会議の録音メモや走り書きを、決まった型の議事録に清書する。
  「議事録にして」「議事録まとめて」と頼まれたら必ずこのスキルを使う。
  会議と関係ない文章の清書には使わない。

直す前の文は、嘘ではないけれど、どの依頼にも当てはまりそうで、どの依頼にも確信が持てません。結果、必要なときに呼ばれず、たまに関係ないときに呼ばれます。直した後は、出番が来たら迷いようがありません。

入れるのは3つ、避けるのは1つ

1つめ、何をするか。「録音メモを議事録に清書する」のように、入力と出力が見える書き方にします。「〜を手伝う」「〜をサポートする」は何も言っていないのと同じです。

2つめ、いつ使うか。「〜と頼まれたら必ずこのスキルを使う」の形で、出番を明文化します。公式ドキュメントも、説明文には「何をするか」と「いつ使うか」の両方を入れるよう求めています。

3つめ、現場の言い回し。ここが僕の34本でいちばん効いている工夫です。自分やチームがふだん使う言葉を、かぎかっこ付きでそのまま並べます。社内で「週報」と呼んでいるものを説明文で「定例報告書」と書くと、当たりません。呼び名は現場の言葉に寄せます。

そして避けるのが、一人称・二人称です。公式ドキュメントは説明文を三人称で書くよう指定していて、「私が手伝います」「あなたはこれを使えます」は避けるべき例として明記されています。説明文はあなたへの宣伝文ではなく、Claudeが選び分けに使う判定材料だからです。

呼ばれすぎたら、「使わない場面」を足します

逆の事故もあります。説明文が広くて、関係ない依頼にまで反応してしまう。このときは「〜には使わない」と1行足すのが効きます。

僕の実例を見せます。例え話のアイデア集をスキルにしたとき、最初は文章の依頼全般に顔を出してきました。いまの説明文にはこう入っています。

このスキルは比喩の「アイデア・着想の参照」としてのみ使用すること。
文体の指定や文章構成の指示は一切含まない。

説明文には「どこまでやるか」だけでなく、「どこからやらないか」も書けるんです。線引きを1行足すだけで、出しゃばりが止まります。

名前と上限の数字

仕様の数字をまとめておきます。

• 名前（name）は最大64文字。使えるのは小文字の英数字とハイフンだけです。「anthropic」「claude」という語は予約されていて使えません
• 説明文（description）は最大1024文字で、空にはできません
• 一覧表に載るときは、補足と合算して1536文字で切られます。長く書くほど安全になるわけではなく、大事な用途ほど先頭に書きます

名前は、公式はprocessing-pdfsのような英語の動詞形を勧めていますが、僕は自分が思い出せることを優先しています。僕の現役スキルにはgijiroku式のローマ字も普通にあります。避けるべきなのはhelperやutilsのような中身の見えない名前だと公式も書いていて、そこさえ外さなければ、ローマ字で何の問題もありません。

いまの1本を、この型に直します

この章のまとめ

説明文に入れるのは、何をするか・いつ使うか・現場の言い回しの3つ。呼ばれすぎには「使わない場面」を1行。三人称で書き、名前は64文字・説明文は1024文字以内、大事な用途は先頭に。ここまでできたら、あとは実際に呼んでみるだけです。次の章で試運転と、呼ばれないときの直し方をやります。