Agent Skill
Skill(SKILL.md)の作り方
「毎回同じ説明をしている」と気づいたら、それはSkillにする合図です。Skill は手順書をファイルとして置いておき、必要になったときだけAIに読ませる仕組み。増やしても普段の動作が重くならないのが要点です。
実務 ・ 読了目安 約10分
Skill とは
Agent Skill は、AIに渡す手順書をフォルダ単位で管理する仕組みです。中心にあるのが SKILL.md という 1枚のファイルで、上部の frontmatter に「いつ使うか」、本文に「どうやるか」を書きます。
プロンプトとの違いは、その場限りかどうかです。プロンプトは打つたびに消えますが、Skill はファイルとして残り、 チームで共有でき、修正の履歴も追えます。AGENTS.md との違いは、常に効くかどうか。AGENTS.md は常時、 Skill は該当する作業のときだけ効きます。
Skillにする判断基準
3段階で読み込まれる(progressive disclosure)
Skill の設計で一番大事なのがこの仕組みです。全部が最初から読まれるわけではありません。 必要になった段階で順に開かれます。
- 1
第1段階: 名前と説明だけ
常時読み込まれるのは frontmatter の name と description だけです。1つのSkillにつき数十トークン程度。だからSkillを100個置いても、普段の動作は重くなりません。
- 2
第2段階: 本文
description を見て「今の作業に関係がある」と判断されたとき、あるいは明示的に呼び出されたときに、SKILL.md の本文が読み込まれます。ここに手順を書きます。
- 3
第3段階: 参照ファイル
本文から参照している別ファイルは、実際に必要になった瞬間に開かれます。長い文例集や規約一覧をここに置けば、使われない限り一切コストがかかりません。
だから description がすべて
ファイル構成
skills/
└─ inquiry-reply/
├─ SKILL.md # 本体。名前・説明・手順(500行以内)
├─ references/
│ ├─ templates.md # 問い合わせ種別ごとの文例(長いのでここに逃がす)
│ └─ ng-expressions.md # 使ってはいけない表現の一覧
└─ assets/
└─ signature.txt # 差し込み用の署名フォルダ名がそのままSkillの単位です。1フォルダ1業務にしておくと、後から入れ替えや削除がしやすくなります。
frontmatter の書き方
SKILL.md の先頭を --- で挟んだ部分が frontmatter です。必須は name と description の2つだけです。
---
name: monthly-report
description: 月次の売上・件数レポートを作る。「月次レポート」「月報」「今月の集計」を頼まれたとき、または data/monthly/*.csv を扱うときに使う。CSVを読み、前月比を出し、決まった書式のMarkdownで返す。
------
name: レポート作成スキル # 日本語・スペースは不可
description: レポートを作ります # いつ使うかが書かれていない
---| 項目 | 制約 | 書き方 |
|---|---|---|
| name | 小文字の英数字とハイフンのみ / 64文字以内 / 予約語不可 | フォルダ名と揃える。表示用の名前ではなく識別子。 |
| description | 1024文字以内 / 空不可 / XMLタグ不可 | 「何をするか」+「いつ使うか(呼び出しの引き金になる言葉)」の2つを必ず入れる。 |
実例: 問い合わせ返信の下書きSkill
どの業種でも起きる作業を例にしています。ポイントは、手順よりも「やってはいけないこと」と「人が確認する箇所」を 明示している点です。文章生成そのものはAIが得意なので、指示すべきは制約のほうです。
---
name: inquiry-reply
description: 問い合わせメールへの返信文の下書きを作る。「返信」「回答文」「お客様への連絡文」の作成を頼まれたときに使う。問い合わせの種類と緊急度に応じて文面と長さを変える。
---
# 問い合わせ返信の下書き
## 使う前に必ず確認する
- 氏名・社名・日付・金額は**入力された文字列をそのまま使う**。推測して補完しない。
- 不明な項目は空欄のまま【要確認: 項目名】と書き、こちらで埋めない。
## 手順
1. 次の項目が揃っているか確認する。欠けていれば質問する。
- 問い合わせの種類(見積依頼 / 仕様相談 / 不具合報告 / その他)
- 相手との関係(新規 / 既存取引先)
- 回答できる範囲(即答可 / 確認が必要 / 回答不可)
2. `references/templates.md` から該当する型を1つ選ぶ。
3. 型に沿って本文を作る。長さは200〜300字を目安にする。
4. 出力の最後に「人が確認する箇所」を箇条書きで付ける。
## 文面のルール
- 結論を最初の2文以内に置く。前置きを長くしない。
- 確約できないことは「確認のうえ改めてご連絡します」と書く。期日を勝手に決めない。
- 社内用語・略語を使わない。
- 謝罪が必要な場合も、原因が未確定なら原因に言及しない。
## 出力の形式
1. 件名
2. 本文(そのまま送信できる形)
3. 「確認してください」の見出しで、日付・氏名・金額・約束事項の該当箇所を列挙
この例で一番重要な行
本文が長くなったら分ける
SKILL.md の本文は500行以内が目安です。超えたら、参照ファイルに逃がします。 分けても損はしません。第3段階の読み込みなので、使われなければコストはゼロです。
## 手順
1. 問い合わせの種類を確認する。
2. `references/templates.md` から該当する型を選ぶ。
- 見積依頼・仕様相談・不具合報告・その他の4種類が定義されている。
3. `references/ng-expressions.md` の語を使っていないか、出力前に照合する。分けるべきもの / 分けないもの
やりがちな失敗
やりがちな失敗
description に「〜を作ります」とだけ書く。
こうする
description は「いつ呼び出すか」の判定材料です。ユーザーが使いそうな言葉(月報、集計、返信など)を実際に含めます。
やりがちな失敗
SKILL.md に文例やチェックリストを全部詰め込み、1000行を超える。
こうする
本文は500行以内を目安に。詳細は references/ に分けて、本文からファイル名で参照します。
やりがちな失敗
name に日本語やスペース、大文字を使う。
こうする
name は小文字の英数字とハイフンのみ、64文字以内です。表示名ではなく識別子だと考えてください。
やりがちな失敗
「丁寧に書いて」「適切に判断して」といった曖昧な指示を並べる。
こうする
判定できる形に落とします。「200〜300字」「結論を最初の2文以内に置く」「不明な項目は【要確認】と書く」のように。
やりがちな失敗
1つのSkillに複数の業務を詰め込む。
こうする
呼び出しの判定が曖昧になります。業務ごとに分けて、description で棲み分けさせます。
やりがちな失敗
実データや顧客名をSkill内の例文に書いてしまう。
こうする
Skillは共有・バージョン管理される前提です。例はすべて架空の名前にします。
公開前チェックリスト
- name は小文字英数字とハイフンのみ、64文字以内
- description に「何をするか」と「いつ使うか」の両方が入っている
- description にユーザーが実際に使う言葉が含まれている(1024文字以内)
- 本文が500行以内に収まっている
- 手順が番号付きで、判定できる基準になっている
- 人が確認すべき箇所を出力させる指示が入っている
- 例文に実在の顧客名・個人名が入っていない
作ったら、必ず一度呼び出させる
Next