AI が実際に使うスキルの説明文の書き方

書き直しの例

例：読み込まれるかの試し方

架空の例です。業務の責任者が上の議事録の説明文を書き、新しいチャットでふつうの頼み方を 8 つ試しました。スキルが読み込まれるべき 5 つと、読み込まれるべきでない 3 つです。その一部：

外れが 1 つありました。みんなは「何が決まったか」とも聞きます。彼女は「〜のときに使う」に「会議で何が決まったかを聞かれたとき」を足し、8 つをもう一度試しました。今度は 5 つが読み込まれ、3 つは読み込まれませんでした。説明文は 200 文字に収まったままです。

書いてみる

1. 三人称の動詞と出来上がるもので始める：「〜を書く」「〜を確かめる」。
2. 何をもとにするかを足す：文字起こし、メモ、請求書。
3. 「〜のときに使う」を足す：みんなが本当に打つ言い方を 2〜3 通り。
4. 1 つのスキルに 1 つの仕事。仕事が 2 つならスキルも 2 つ。
5. 読み込まれるべき 5 つと、べきでない 3 つの頼み方を新しいチャットで試し、すべて合うまで直す。

次の一歩：全員に 1 つの版を

一度整えた説明文は、そのまま全員の AI に届くべきです。1 つの版を保つ方法はAI のプロンプトを小さなチームで安く共有する方法で比べています。ほかの項目はSKILL.md の書き方で。

よくある質問

良いスキルの説明文とは？

何をし、いつ使うかを、三人称で、みんなが実際に打つ言葉で書いたものです。Claude のドキュメントの型は「Processes Excel files and generates reports」で、「I can help you process Excel files」ではありません。出来上がるものを書き、続けて「〜を頼まれたときに使う」を 2〜3 通りの実際の言い方で書きます。

スキルの説明文は何文字まで？

Agent Skills の仕様と Claude Docs では 1,024 文字までです。Claude ヘルプセンターは claude.ai にアップロードするスキルを 200 文字までとしているので、そこで使う説明文は 200 文字に収めます。

Claude が自分のスキルを使わないのはなぜ？

たいていは説明文です。作業の前に読み込まれるのは name と description だけなので、あいまいな説明（「文書を手伝う」）は合いません。出来上がるものとみんなが打つ言葉で書き直し、新しいチャットでふつうの頼み方で試します。