最近、CursorやGitHub Copilot、Claude CodeといったAI搭載エディタ・AIエージェントの進化が目覚ましいですが、実際に業務のプロジェクトに適用しようとすると「汎用的な知識はあるけれど、自社の独自フレームワークや固有のデプロイ手順を知らない」という壁にぶつかることが多いのではないでしょうか。
本記事では、この「コンテキスト不足」という課題を根本から解決するためにAnthropicが開発し、オープン標準として公開された仕様「Agent Skills」について、そのアーキテクチャの根幹から具体的な実装例までを徹底解説します。
1. なぜ今「Agent Skills」が必要なのか？（Why）
現在の汎用的なAIエージェントは非常に賢いですが、私たちのプロジェクト固有のルールや手順を知りません。これを解決するために、これまで私たちは以下の2つのアプローチをとってきました。
- プロンプトエンジニアリング（System Prompt）:
毎回「我々のプロジェクトではTypeScriptを使い、テストはVitestで書くこと。データベースのマイグレーションは...」と長大なプロンプトを入力する手法。
*課題*: プロンプトの管理が煩雑になり、コンテキストウィンドウ（LLMが一度に処理できる文字数）を無駄に消費します。
- RAG（Retrieval-Augmented Generation）:
社内ドキュメントをベクトルデータベース化し、AIが検索して参照する手法。
*課題*: 関連する文章は検索できても、「AをしてからBをする」といった厳密な「ワークフロー（手順）」をAIに強制させるのには不向きです。
このギャップを埋めるのが Agent Skills です。
Agent Skillsは、「特定のタスクを実行するための具体的な指示書やスクリプト」を、バージョン管理可能な軽量なフォルダ単位（スキル）でAIエージェントに渡すための標準仕様です。
2. Agent Skills のコアアーキテクチャ：「段階的開示」による極限の効率化
Agent Skillsの最大の技術的なブレイクスルーは、「Progressive Disclosure（段階的開示）」 という仕組みを採用している点です。
大量のスキル（例えば「PDFの処理手順」「DBマイグレーション手順」「APIのデプロイ手順」など）をすべてAIに最初から読み込ませると、不要な情報でトークンが溢れてしまい、肝心の指示を忘れたり（Lost in the Middle現象）、APIコストが跳ね上がったりします。
Agent Skills対応のエージェントは、以下の3段階で情報を読み込みます。
Step 1: Discovery（発見）
エージェントの起動時、システムに登録されている全スキルのうち、「名前（name）」と「短い説明（description）」だけを読み込みます。（約100トークン程度）
これにより、エージェントは「どんなスキルが手札にあるか」だけをインデックスします。
Step 2: Activation（有効化）
ユーザーが「データベースのマイグレーションを実行して」と指示を出したとします。
エージェントは、Step 1で読み込んだDescriptionの中から最も適したスキル（例：`db-migration`）を特定し、その時点で初めてスキルの詳細な指示書（SKILL.md 本文）をコンテキストにロードします。
Step 3: Execution（実行）
エージェントは読み込んだ `SKILL.md` の指示に従い、必要なスクリプト（`.sh` や `.py` など）を実行したり、参照ドキュメントを読み込んだりしてタスクを完遂します。
この仕組みにより、何十、何百という社内ワークフローをスキルとして定義しておきながら、コンテキストの消費を最小限に抑えることができるのです。
3. 仕様（Specification）の全貌とディレクトリ構造
Agent Skillsの実体は、特定の構造を持った単なる「ディレクトリ（フォルダ）」です。
最小構成は、ディレクトリ内に `SKILL.md` が1つあるだけです。
my-skill/
├── SKILL.md # 必須: メタデータ（Frontmatter） + 実行指示
├── scripts/ # 任意: 実行可能なスクリプト群（.sh, .js, .py 等）
├── references/ # 任意: 追加のリファレンスドキュメント
└── assets/ # 任意: テンプレートファイルなどの静的リソースSKILL.md の書き方
`SKILL.md` は、上部にYAMLのFrontmatter（メタデータ）を持ち、その下にMarkdownでAIへの指示を書きます。
---
name: db-migration
description: データベースのマイグレーションを実行する際に使用します。ユーザーが「DBを更新して」「マイグレーションして」と言った場合にアクティブになります。
---
# データベースマイグレーションの手順
1. まず、`scripts/check_diff.sh` を実行して、未適用のマイグレーションファイルがないか確認してください。
2. 差分がある場合、`npm run typeorm migration:run` を実行してください。
3. 実行後、エラーが出た場合は `references/error_handling.md` を参照して復旧手順を踏んでください。ここで最も重要なのは `description` です。エージェントはユーザーの自然言語のプロンプトと、この `description` を照らし合わせてスキルを発動させるため、「どのようなキーワードや状況で使うべきか」を具体的に書く必要があります。
4. 実際に作ってみる：VS Code / GitHub Copilot での実装例
Agent Skillsは既にオープンエコシステムとなっており、GitHub Copilot, Cursor, Claude Code, OpenHandsなど、多くの主要クライアントが対応しています。
ここでは、VS Code + GitHub Copilot を使って、「サイコロを振る」簡単なスキルを自作してみましょう。
手順
VS Codeはデフォルトでプロジェクト直下の `.agents/skills/` ディレクトリを読み込みます。
`.agents/skills/roll-dice/SKILL.md` を作成し、以下のように記述します。
---
name: roll-dice
description: 乱数ジェネレーターを使ってサイコロを振ります。「サイコロを振って」「d20を振って」などと言われた場合に使用してください。
---
指定された面数のサイコロを振るために、以下のシェルコマンドを実行します。
```bash
echo $((RANDOM % <sides> + 1))
```
※ `<sides>` の部分は、ユーザーの指定に合わせてAIが動的に数値を置き換えて実行します（例：d20なら20）。実行と検証
VS CodeのCopilot Chatパネルを開き、Agentモードを選択します。
プロンプトに `/skills` と入力すると、読み込まれているスキル一覧に `roll-dice` が表示されるはずです。
「20面体のサイコロを振って（Roll a d20）」とチャットに入力すると、エージェントは `roll-dice` スキルをActivationし、内包されたシェルコマンドをあなたのターミナルで実行する許可を求めてきます。許可すると、実際に乱数が生成されて結果が返ってきます。
5. まとめと今後の展望：AI開発の標準インフラへ
Agent Skillsは、「AIエージェントに自社固有の業務を教える」ための最もスマートでメンテナンス性の高いアプローチです。
【失敗しないためのハマりどころ（Tips）】
- スキルの粒度を大きくしすぎない: 1つのスキルに「デプロイ手順」と「テスト手順」を詰め込むと、LLMが混乱します。Unix哲学と同じく「1つのスキルは1つの役割」に徹することが成功の鍵です。
- Descriptionのチューニング: 似たようなスキルが複数あるとエージェントが迷います。Descriptionには「いつ使うべきか」「いつ使うべきではないか」を明確に書きましょう。
チームのベテランエンジニアが頭の中に持っている「秘伝のデプロイ手順」や「トラブルシューティングのワークフロー」をAgent Skillsとしてリポジトリ（`.agents/skills/`）にコミットしておくことで、新しく入ったメンバーでも、AIエージェント経由でベテランと同じ品質・手順でタスクを実行できるようになります。
AIはもはや「質問に答えるだけのツール」ではなく、「社内インフラのオペレーター」になりつつあります。Agent Skillsを活用し、自社専用の最強のエージェントチームを構築してみてはいかがでしょうか。
