Agent Skills（agentskills.io）の仕様と設計：手順書の段階的開示とディレクトリ標準
日々の開発・インフラ検証の備忘録として残している個人ノートです。手元環境での動作ログをもとにまとめています。環境差異等もあるため、参考にされる場合はご自身の環境で検証の上ご活用ください。
はじめに
AI コーディングエージェントにデプロイ手順、データベースマイグレーション、障害調査などの定型タスクを実行させる際、すべての詳細手順を AGENTS.md などのルールファイルに記述すると、プロンプトが肥大化して Context Bloat（トークン消費の増大） が発生します。
さらに、スタンフォード大学などの研究 『Lost in the Middle』(Liu et al., 2023) が実証した通り、プロンプトが長大化するほど中盤に書かれた指示への注意（Attention）が著しく低下する Attention Dilution（重要指示の埋没・見落とし） が発生します。
この問題を解決し、専門手順や実行コードをオンデマンドで読み込むオープン標準規格が Agent Skills（agentskills.io） です。
本記事では、agentskills.io の公式仕様、中核となる 段階的開示（Progressive Disclosure） のアーキテクチャ、標準ディレクトリ構造、およびトークン効率と決定論的実行を両立する設計原則をまとめます。
段階的開示（Progressive Disclosure）のアーキテクチャ
Agent Skills の最大の特徴は、「必要な情報だけを、必要なタイミングで読み込む」 という 3 段階のライフサイクル設計にあります。
flowchart TD
Phase1["1. 探索フェーズ（Discovery）
起動時：name と description のみ読み込み
（30〜100 トークン / スキル）"]
-->|"ユーザーの指示が合致"| Phase2["2. 発動フェーズ（Triggering）
タスク発生時：SKILL.md 本文（手順書）を展開"]
-->|"詳細仕様や自動化が必要"| Phase3["3. 実行フェーズ（Execution）
オンデマンド：scripts/ 実行、references/ 参照"]flowchart TD
Phase1["1. 探索フェーズ（Discovery）
起動時：name と description のみ読み込み
（30〜100 トークン / スキル）"]
-->|"ユーザーの指示が合致"| Phase2["2. 発動フェーズ（Triggering）
タスク発生時：SKILL.md 本文（手順書）を展開"]
-->|"詳細仕様や自動化が必要"| Phase3["3. 実行フェーズ（Execution）
オンデマンド：scripts/ 実行、references/ 参照"]flowchart TD
Phase1["1. 探索フェーズ（Discovery）
起動時：name と description のみ読み込み
（30〜100 トークン / スキル）"]
-->|"ユーザーの指示が合致"| Phase2["2. 発動フェーズ（Triggering）
タスク発生時：SKILL.md 本文（手順書）を展開"]
-->|"詳細仕様や自動化が必要"| Phase3["3. 実行フェーズ（Execution）
オンデマンド：scripts/ 実行、references/ 参照"] | |
1. 探索フェーズ（Discovery Phase）
エージェント起動時、インストールされている全スキルの SKILL.md から YAML フロントマター（name と description）のみ をインデックスとしてメモリに読み込みます。
1 スキルあたりわずか 30〜100 トークン程度しか消費しないため、数十〜数百個のスキルが存在してもコンテキスト上限を圧迫しません。
2. 発動フェーズ（Triggering Phase）
ユーザーのプロンプトを評価し、「このタスクにはあのスキルが必要だ」とエージェントが判断した瞬間に、該当する SKILL.md の 本文（Markdown 手順書） をコンテキストに展開します。
3. 実行フェーズ（Execution Phase）
スキルの手順書に従って作業を進める中で、追加のドキュメントが必要になった場合は references/ をピンポイントで参照し、自動化スクリプトが必要な場合は scripts/ を実行します。
Agent Skills の標準ディレクトリ構造
agentskills.io 仕様では、1 つのスキルを独立したフォルダとして構成します。
| |
各サブディレクトリの役割
SKILL.md（必須）
スキルのエントリポイントです。YAML フロントマターと Markdown 本文で構成され、作業の大まかな流れや判断基準を記述します。
references/（任意：参照ドキュメント）
SKILL.md にすべて書ききれない 詳細な API 仕様書、エラーコード対応表、データスキーマ定義 などを格納します。
- メリット:
SKILL.md自体をスリムに保ち、エージェントが「特定のエラーが発生したとき」「特定パラメータを調べるとき」だけ該当ファイルを読めるようにします。 - 記述例:
SKILL.md内に[エラー一覧](references/error_codes.md)のように相対パスでリンクを記載します。
scripts/（任意：実行コード）
エージェントがシェルから直接実行できるスクリプト（Bash, Python, Node.js 等）を配置します。
- メリット: AI に複雑なワンライナーをアドホックに生成させるのではなく、テスト済みの決定論的なコードを実行させることで作業の再現性と安全性を担保します。
assets/（任意：静的アセット）
テンプレートファイル、設定の雛形、画像データなどを配置します。
evals/（任意：評価テスト）
スキルが想定通りに動作するかを検証するためのプロンプト例やテストケースを定義します。
SKILL.md の仕様と記述例
1. YAML フロントマターの仕様
SKILL.md の先頭には、探索フェーズで使われるメタデータを YAML 形式で定義します。
| フィールド | 必須 / 任意 | 型 | 説明 |
|---|---|---|---|
name | 必須 | string | スキルの一意な識別子（1〜64文字、小文字英数字・ハイフン） |
description | 必須 | string | スキルの役割と 発動条件（トリガー） を自然言語で記載（最大 1024 文字） |
license | 任意 | string | ライセンス情報（MIT, Apache-2.0 等） |
compatibility | 任意 | string | 動作要件や前提環境（例: Linux/macOS with Docker） |
metadata | 任意 | object | 任意のカスタムキーバリューストア |
IMPORTANT
description はトリガーの精度を左右する
エージェントは description を読んでスキルの使用可否を判断します。「何をするか」だけでなく、「どんな状況・指示のときに使うべきか（Use this skill when…）」を明確に記述することが極めて重要です。
2. SKILL.md の実践例
| |
- マイグレーションの適用:
1npm run migrate:up - 整合性検証:
- 適用後、以下のテストを実行してエラーが出ないことを確認する。
1npm run test:db - ロールバック手順（エラー発生時）:
- テストが失敗した場合は直ちにロールバックを実行する。
1npm run migrate:down- 失敗時のエラーコード詳細は トラブルシューティング を参照。
| |