SASmall AI System

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回以上した」「説明を省くと品質が落ちる」「担当者が変わると出来上がりが変わる」。 このどれかに当てはまる作業は、Skill にする価値があります。

3段階で読み込まれる(progressive disclosure)

Skill の設計で一番大事なのがこの仕組みです。全部が最初から読まれるわけではありません。 必要になった段階で順に開かれます。

  1. 1

    第1段階: 名前と説明だけ

    常時読み込まれるのは frontmatter の name と description だけです。1つのSkillにつき数十トークン程度。だからSkillを100個置いても、普段の動作は重くなりません。

  2. 2

    第2段階: 本文

    description を見て「今の作業に関係がある」と判断されたとき、あるいは明示的に呼び出されたときに、SKILL.md の本文が読み込まれます。ここに手順を書きます。

  3. 3

    第3段階: 参照ファイル

    本文から参照している別ファイルは、実際に必要になった瞬間に開かれます。長い文例集や規約一覧をここに置けば、使われない限り一切コストがかかりません。

だから description がすべて

第1段階で読まれるのは description だけです。ここに「いつ使うか」が書かれていないと、 どれだけ良い手順を本文に書いても呼び出されません。Skill が動かない原因の大半はここです。

ファイル構成

ディレクトリ構成
skills/
└─ inquiry-reply/
   ├─ SKILL.md              # 本体。名前・説明・手順(500行以内)
   ├─ references/
   │  ├─ templates.md       # 問い合わせ種別ごとの文例(長いのでここに逃がす)
   │  └─ ng-expressions.md  # 使ってはいけない表現の一覧
   └─ assets/
      └─ signature.txt      # 差し込み用の署名
SKILL.md は必須。references / assets は必要になってから作ればよい。

フォルダ名がそのままSkillの単位です。1フォルダ1業務にしておくと、後から入れ替えや削除がしやすくなります。

frontmatter の書き方

SKILL.md の先頭を --- で挟んだ部分が frontmatter です。必須は namedescription の2つだけです。

良い例
---
name: monthly-report
description: 月次の売上・件数レポートを作る。「月次レポート」「月報」「今月の集計」を頼まれたとき、または data/monthly/*.csv を扱うときに使う。CSVを読み、前月比を出し、決まった書式のMarkdownで返す。
---
いつ使うか(月次レポート/月報/今月の集計/対象ファイル)が具体的に書かれている。
悪い例
---
name: レポート作成スキル          # 日本語・スペースは不可
description: レポートを作ります   # いつ使うかが書かれていない
---
name の形式が不正で、description からは呼び出す場面が判定できない。
項目制約書き方
name小文字の英数字とハイフンのみ / 64文字以内 / 予約語不可フォルダ名と揃える。表示用の名前ではなく識別子。
description1024文字以内 / 空不可 / XMLタグ不可「何をするか」+「いつ使うか(呼び出しの引き金になる言葉)」の2つを必ず入れる。

実例: 問い合わせ返信の下書きSkill

どの業種でも起きる作業を例にしています。ポイントは、手順よりも「やってはいけないこと」と「人が確認する箇所」を 明示している点です。文章生成そのものはAIが得意なので、指示すべきは制約のほうです。

skills/inquiry-reply/SKILL.md
---
name: inquiry-reply
description: 問い合わせメールへの返信文の下書きを作る。「返信」「回答文」「お客様への連絡文」の作成を頼まれたときに使う。問い合わせの種類と緊急度に応じて文面と長さを変える。
---

# 問い合わせ返信の下書き

## 使う前に必ず確認する
- 氏名・社名・日付・金額は**入力された文字列をそのまま使う**。推測して補完しない。
- 不明な項目は空欄のまま【要確認: 項目名】と書き、こちらで埋めない。

## 手順
1. 次の項目が揃っているか確認する。欠けていれば質問する。
   - 問い合わせの種類(見積依頼 / 仕様相談 / 不具合報告 / その他)
   - 相手との関係(新規 / 既存取引先)
   - 回答できる範囲(即答可 / 確認が必要 / 回答不可)
2. `references/templates.md` から該当する型を1つ選ぶ。
3. 型に沿って本文を作る。長さは200〜300字を目安にする。
4. 出力の最後に「人が確認する箇所」を箇条書きで付ける。

## 文面のルール
- 結論を最初の2文以内に置く。前置きを長くしない。
- 確約できないことは「確認のうえ改めてご連絡します」と書く。期日を勝手に決めない。
- 社内用語・略語を使わない。
- 謝罪が必要な場合も、原因が未確定なら原因に言及しない。

## 出力の形式
1. 件名
2. 本文(そのまま送信できる形)
3. 「確認してください」の見出しで、日付・氏名・金額・約束事項の該当箇所を列挙

この例で一番重要な行

「不明な項目は空欄のまま【要確認: 項目名】と書き、こちらで埋めない」。 AIは空欄を嫌ってもっともらしく埋めます。氏名・日付・金額・約束事項はそれが事故に直結するため、 埋めさせない指示を明示的に書きます。

本文が長くなったら分ける

SKILL.md の本文は500行以内が目安です。超えたら、参照ファイルに逃がします。 分けても損はしません。第3段階の読み込みなので、使われなければコストはゼロです。

SKILL.md(抜粋)
## 手順
1. 問い合わせの種類を確認する。
2. `references/templates.md` から該当する型を選ぶ。
   - 見積依頼・仕様相談・不具合報告・その他の4種類が定義されている。
3. `references/ng-expressions.md` の語を使っていないか、出力前に照合する。
本文からはファイル名と「そこに何があるか」を1行で示す。中身は必要になったときに開かれる。

分けるべきもの / 分けないもの

分けるのは、長い一覧・文例集・規約全文・APIの詳細仕様。 分けないのは、判断の基準そのもの(何を選ぶか、いつ止まるか)。判断基準は本文に置いてください。

やりがちな失敗

やりがちな失敗

description に「〜を作ります」とだけ書く。

こうする

description は「いつ呼び出すか」の判定材料です。ユーザーが使いそうな言葉(月報、集計、返信など)を実際に含めます。

やりがちな失敗

SKILL.md に文例やチェックリストを全部詰め込み、1000行を超える。

こうする

本文は500行以内を目安に。詳細は references/ に分けて、本文からファイル名で参照します。

やりがちな失敗

name に日本語やスペース、大文字を使う。

こうする

name は小文字の英数字とハイフンのみ、64文字以内です。表示名ではなく識別子だと考えてください。

やりがちな失敗

「丁寧に書いて」「適切に判断して」といった曖昧な指示を並べる。

こうする

判定できる形に落とします。「200〜300字」「結論を最初の2文以内に置く」「不明な項目は【要確認】と書く」のように。

やりがちな失敗

1つのSkillに複数の業務を詰め込む。

こうする

呼び出しの判定が曖昧になります。業務ごとに分けて、description で棲み分けさせます。

やりがちな失敗

実データや顧客名をSkill内の例文に書いてしまう。

こうする

Skillは共有・バージョン管理される前提です。例はすべて架空の名前にします。

公開前チェックリスト

  • name は小文字英数字とハイフンのみ、64文字以内
  • description に「何をするか」と「いつ使うか」の両方が入っている
  • description にユーザーが実際に使う言葉が含まれている(1024文字以内)
  • 本文が500行以内に収まっている
  • 手順が番号付きで、判定できる基準になっている
  • 人が確認すべき箇所を出力させる指示が入っている
  • 例文に実在の顧客名・個人名が入っていない

作ったら、必ず一度呼び出させる

Skill は「置いたのに呼ばれない」が最も多い失敗です。作ったら、実際の言い回しで指示を出して、 意図通り呼び出されるか確認してください。呼ばれなければ description を直します。