先に結論
を一通り読んで、一番強く感じたのはこれです。
Agent Skills は、単なるプロンプト集ではありません。
AI エージェントに「この仕事は、こう進める」という手順・判断基準・補助ファイルを渡すための、かなり実務寄りの標準フォーマットです。
もっと短く言うと、
AI に全部を覚えさせるのではなく、必要な時に必要な仕事のやり方を読み込ませる仕組み
だと思いました。
公式ドキュメントでは、Agent Skills は SKILL.md を含むフォルダとして定義され、そこに name、description、実行手順、必要に応じて scripts/、references/、assets/ などをまとめられると説明されています。(エージェントスキル)
今回は、Agent Skills の公式サイトを読んで、開発者視点で「これは何が本質なのか」を整理してみます。公式のドキュメント一覧は llms.txt にまとまっており、Overview、Specification、Quickstart、Best practices、Evaluating、Using scripts、Client implementation などが用意されています。(エージェントスキル)
Agent Skillsとは何か
Agent Skills は、AI エージェントに新しい能力を追加するための軽量なフォーマットです。
最小構成はかなりシンプルです。
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
必須なのは SKILL.md です。
ここにメタデータと、エージェントが従うべき手順を書きます。
たとえば、PDF処理、コードレビュー、データ分析、社内ドキュメント作成、リリース確認、障害対応など、毎回同じような判断や手順が必要になる作業があります。
これまでは、そういう作業を毎回プロンプトで説明していました。
でも Agent Skills では、それをスキルとしてフォルダに切り出せます。
これはかなり大きいです。
プロンプトは、その場限りになりやすい。
でも Skill は、再利用できる。
プロジェクトにも置ける。
バージョン管理もできる。
チームで改善できる。
つまり、AI に対する「作業手順のコード化」に近いものだと思います。
なぜ今 Agent Skills が必要なのか
AI エージェントはかなり賢くなりました。
コードも書ける。
ファイルも読める。
ツールも呼べる。
長いタスクもある程度進められる。
ただ、実務ではまだよく詰まります。
理由は、モデルの能力不足だけではありません。
多くの場合、エージェントが知らないのは「一般知識」ではなく、次のような現場固有の情報です。
- このチームでは、レビュー時に何を見るのか
- このプロジェクトでは、どのAPIを使うべきなのか
- 失敗時にどこまでリトライしてよいのか
- 出力フォーマットはどうすべきなのか
- どのファイルを正本として扱うのか
- どの手順は絶対に飛ばしてはいけないのか
公式ドキュメントでも、Skills は手続き的知識や会社・チーム・ユーザー固有のコンテキストを、ポータブルでバージョン管理可能なフォルダとしてまとめ、必要に応じてエージェントが読み込むものだと説明されています。(エージェントスキル)
ここが本質だと思います。
AI エージェントで難しいのは、単に「賢くすること」ではありません。
仕事のやり方を、再利用可能な形で渡すことです。
大事な仕組みは Progressive Disclosure
Agent Skills の設計で一番面白いのは、Progressive Disclosure です。
日本語にすると「段階的な開示」です。
エージェントは最初から全部のスキル本文を読むわけではありません。
流れはだいたいこうです。
- 起動時に、各 Skill の
nameとdescriptionだけを見る - ユーザーの依頼に合う Skill があれば、その
SKILL.mdを読む - 必要になった時だけ、
scripts/、references/、assets/を読む
公式ドキュメントでも、Discovery、Activation、Execution の3段階でスキルを読み込むと説明されています。(エージェントスキル)
これはかなり現実的です。
全部のルールを常にコンテキストに入れると、すぐ重くなります。
しかも、関係ないルールが混ざると、AI の判断もブレます。
なので、必要な時だけ読む。
これは RAG にも近い考え方ですが、検索対象が「知識」だけではなく「作業手順」になっている点が違います。
SKILL.mdは「AI向けのREADME」ではなく「実行契約」
SKILL.md は、ただの説明文ではありません。
エージェントにとっては、
このタスクでは、こう判断して、こう動いて、こう検証する
という実行契約に近いです。
仕様では、SKILL.md は YAML frontmatter と Markdown 本文で構成されます。必須フィールドは name と description で、任意で license、compatibility、metadata、allowed-tools なども書けます。(エージェントスキル)
たとえば、こんな感じです。
---
name: pull-request-review
description: Use this skill when reviewing pull requests for backend services, especially when checking API compatibility, transaction safety, error handling, and regression risk.
---
## Review workflow
1. Read the PR description and changed files.
2. Identify the main behavior change.
3. Check API compatibility.
4. Check transaction boundaries and rollback behavior.
5. Check error handling and logging.
6. Summarize risks and required fixes.
## Gotchas
- Do not only comment on naming or formatting.
- Always check whether the change is safe for existing clients.
- If the PR changes retry logic, check idempotency.
これだけでも、普通の「レビューして」よりかなり強くなります。
なぜなら、エージェントが見るべき観点が明確になるからです。
学び1: description がかなり重要
Agent Skills では、description がかなり重要です。
ここが弱いと、そもそも Skill が発火しません。
逆に広すぎると、関係ない場面でも発火します。
公式ドキュメントでも、description はエージェントがその Skill を読み込むかどうかを判断する主要な仕組みだと説明されています。さらに、「Use this skill when...」のように、エージェントへの指示として書くことが推奨されています。(エージェントスキル)
これは、普通の説明文とは少し違います。
悪い例です。
description: Helps with reviews.
これだと広すぎます。
よい例はこうです。
description: Use this skill when reviewing backend API pull requests, especially for compatibility, transaction safety, error handling, idempotency, and regression risk.
何をするか。
いつ使うか。
どんな言葉に反応すべきか。
ここまで書く必要があります。
つまり、description はスキルの紹介文ではなく、トリガー条件です。
学び2: 汎用ベストプラクティスだけでは弱い
Agent Skills の Best practices で一番刺さったのは、「実際の専門知識から作る」という点です。
LLM に「良いスキルを作って」と頼むだけだと、どうしても一般論になりやすいです。
- エラーを適切に処理する
- ベストプラクティスに従う
- セキュリティを考慮する
こういう指示は、悪くはありません。
でも、現場では弱いです。
本当に価値があるのは、もっと具体的な情報です。
- このAPIではこの例外がよく起きる
- このテーブルは soft delete なので必ず条件を付ける
- このCLIはこの順番で実行しないと壊れる
- この帳票はこのテンプレートを使う
- このレビューでは障害時のふるまいを必ず見る
公式ドキュメントでも、効果的な Skill は実際のタスク、社内ドキュメント、runbook、style guide、API仕様、コードレビューコメント、issue tracker、障害事例などから作るべきだと説明されています。(エージェントスキル)
ここはかなり本質的です。
Agent Skills は、AI に一般論を教えるものではありません。
現場で何度も出てくる判断を、再利用できる形にするものです。
学び3: コンテキストは貴重なので、全部書かない
Skill は便利ですが、何でも書けばよいわけではありません。
SKILL.md が長すぎると、エージェントは重要な部分を見失います。
また、関係ない情報が混ざると、無駄な行動も増えます。
公式ドキュメントでは、SKILL.md はコア手順に絞り、詳細情報は references/ などに分けることが推奨されています。また、メインの SKILL.md は500行未満、本文は5,000トークン未満が目安とされています。(エージェントスキル)
ここで大事なのは、
AI が知らないことだけを書く
という感覚です。
AI は、HTTPとは何か、JSONとは何か、PDFとは何か、基本的なGit操作とは何か、だいたい知っています。
だから、そこを書く必要はありません。
書くべきなのは、AI がその現場で間違えやすいことです。
- このプロジェクト固有の命名規則
- 本番反映前に必ず見るダッシュボード
- 障害時に戻してはいけない順番
- 古い顧客だけに必要な互換処理
- 過去に事故った条件
こういう情報にこそ価値があります。
学び4: scripts/ はエージェントを安定させる
Agent Skills では、scripts/ を同梱できます。
これがかなり実務的です。
AI に毎回コードを書かせるより、よく使う処理はスクリプトにしておいた方が安定します。
たとえば、
- CSV検証
- PDF抽出
- JSON schema チェック
- PR差分の集計
- ドキュメント変換
- 出力ファイルの妥当性チェック
こういうものは、AI に毎回作らせるより、テスト済みスクリプトを同梱した方がいいです。
公式ドキュメントでも、Skill は shell command や scripts/ ディレクトリ内の再利用可能なスクリプトを使えると説明されています。また、複雑なコマンドは scripts/ に移す方が信頼性が高いとされています。(エージェントスキル)
これは、AI エージェントの使い方としてかなり重要です。
AI に全部考えさせるのではなく、
決まった作業はスクリプトに逃がす。
AI は判断や編集に使う。
機械的な検証はスクリプトに任せる。
この分担ができると、Agent はかなり安定します。
学び5: Skillも評価しないと劣化する
Agent Skills は作って終わりではありません。
むしろ、作ってからが本番です。
公式ドキュメントでは、Skill の評価として、実際に近いテストケースを作り、Skill あり・なしで比較し、assertion、grading、benchmark を使って改善する流れが説明されています。(エージェントスキル)
これはかなり大事です。
なぜなら、Skill は書いた本人には良く見えるからです。
でも実際には、
- 発火すべき場面で発火しない
- 関係ない場面で発火する
- 手順が細かすぎて遅くなる
- 曖昧な指示で毎回違う動きをする
- 古い前提が残っている
- スクリプトの使い方が分かりにくい
といった問題が起きます。
なので、Skill もテストする必要があります。
ソフトウェアと同じです。
最初から完璧な Skill を作るのではなく、実行ログを見て、失敗を見て、削るところは削り、足りないところを足す。
この改善ループがないと、Skill はただの長いプロンプト集になってしまいます。
今すぐ作るなら、こう始める
個人的には、最初の Skill は大きくしない方がよいと思います。
いきなり「全部入りの開発Skill」を作ると、だいたい失敗します。
最初は、次のような小さい単位がよいです。
- PRレビューSkill
- リリース前チェックSkill
- 障害報告まとめSkill
- 議事録からAction Itemを抽出するSkill
- 特定フレームワークのテスト作成Skill
- 社内テンプレートに沿った提案資料作成Skill
- CSV分析レポート生成Skill
ポイントは、何でもできる Skill にしないことです。
1つの Skill は、1つのまとまった仕事に絞る。
そして、実際の作業で使う。
失敗したら直す。
何度も出る処理は script にする。
詳細資料は references に分ける。
これが一番現実的だと思います。
まとめ
Agent Skills は、AI エージェントを強くするための新しい部品です。
ただし、本質は「便利なプロンプト集」ではありません。
本当に大事なのは、
- 作業手順を再利用できる形にする
- 現場固有の判断基準を渡す
- 必要な時だけ読み込ませる
- スクリプトで安定化する
- 評価しながら改善する
という点です。
AI エージェントが増えるほど、毎回プロンプトで説明する運用はしんどくなります。
その代わりに、チームの作業知識を Skill として整備していく。
これからの AI 開発では、モデルを選ぶ力だけでなく、
AI に渡す仕事のやり方を設計する力
がかなり重要になると思います。