Agent Skill の書き方:SKILL.md の構成、呼び出される description、よくある5つの失敗

Skill とは、再利用できる作業手順を AI 向けにまとめたフォルダで、中心になるのは SKILL.md です。この記事では、SKILL.md がどんな要素でできているか、なぜ description が呼び出されるかどうかを決めるのか、どの内容を別ファイルに分けるべきか、そして Skill を書くときによくある5つの失敗を解説します。

Agent Skill 書き方SKILL.md 書き方SKILL.md フォーマットClaude Skill 作り方Codex SkillsAI スキル 作成

同じタスクのたびに、AI に手順やフォーマット、注意点を毎回説明している。そんなときこそ Skill にまとめるタイミングです。Skill の正体は1つのフォルダです。中に SKILL.md を置いて「いつ使うか、どうやるか」をはっきり書き、必要に応じてスクリプトや参考資料、テンプレートを入れます。AI は普段、各 Skill の名前と一文の説明だけを見ていて、使えそうだと判断したときにだけ全文を読み込みます。そのため Skill を何十個入れても、コンテキストを圧迫しません。

SKILL.md は3つの部分でできている

1つ目は冒頭のメタ情報で、特に重要なのが name と description です。name は短い識別子、description はこの Skill が何をするのか、どんな場面で使うべきかを1〜2文で説明します。2つ目は本文で、具体的な手順を書きます。最初に何をして、次に何をするか、どんな形式で出力するか、例外が起きたらどう対処するか。3つ目は添付ファイルで、同じフォルダに置きます。データ処理用のスクリプト、長い仕様書、出力テンプレートなどです。本文には、どのタイミングでどのファイルを読むかを明記しておきます。

description が呼び出されるかどうかを決める

よく書けているのに一度も使われない Skill は多く、その原因はほぼ description にあります。AI は description を見て「このリクエストにこの Skill を使うべきか」を判断するので、検索キーワードのように具体的である必要があります。ユーザーがどう言うか、どんな種類のファイルを扱うか、どんな成果物を出すかを書きましょう。「ドキュメント処理を手伝う」では曖昧すぎます。「会議の録音の文字起こしを、ToDo 付きの議事録に整理する。ユーザーが議事録、録音の整理、会議後のまとめに触れたときに使う」のほうがずっと明確です。

本文には手順を書き、理屈は書かない

本文は AI が実行するためのもので、人が読む説明書ではありません。番号付きの手順にして、1ステップに1つの動作を書きます。判断条件は「ファイルが100行を超えたら先に分割する」のように明確にします。完全な入出力の例を1つ示すほうが、原則を3段落書くより役に立ちます。フォーマット変換やデータ計算のように正確な実行が必要な部分は、できるだけスクリプトにしてフォルダに入れ、AI が毎回自分で書き直すのではなくスクリプトを呼び出すようにしましょう。

Skill を書くときによくある5つの失敗

1つ目は description が広すぎること。呼ばれるべきときに呼ばれず、呼ばれるべきでないときに呼ばれてしまいます。2つ目はすべてを SKILL.md に詰め込むこと。何千字もの本文を毎回読むことになり、遅いうえに要点を見落としやすくなります。長い資料は添付ファイルに分けるべきです。3つ目は原則だけ書いて例を示さないこと。「簡潔でプロフェッショナルに」の受け取り方は、AI とあなたで違います。4つ目はテストをせず、書いてすぐ公開すること。実際のリクエストをいくつか用意して、正しく呼び出されるか、出力が基準を満たすかを確認すべきです。5つ目は API キーやアカウント情報を Skill に書き込むこと。Skill は共有・コピーされることが多いので、機密情報は環境変数に置きましょう。

個人の Skill から企業のスキルパッケージへ

個人で使う Skill なら、書いて動けばそれで十分です。チームや企業で共有するとなると、バージョン管理、セキュリティレビュー、効果の評価、統一的な配布まで考える必要があります。これが「便利な Skill 1つ」と「企業向け Skill スキルパッケージ」との距離です。

図解 Skill は56講の図解で Skill の仕組みから解説する講座です(講座は中国語です)。紙のラフスケッチから始めて、テストとセキュリティレビューを経て企業の SkillHub に公開できるスキルパッケージを、一歩ずつ作り上げていきます。最初の6講は無料です。