Claude Codeを使って開発する中で、以前から「Skills」や「Subagents」という仕組みは知っていました。
たとえば、
- コードレビュー用のSkill
- 記事を書くためのSkill
- 特定の設計ルールを参照するSkill
といったものを用意しておけば、毎回同じ指示をプロンプトに書かなくても、AIエージェントに一定のルールを持たせることができます。
私はこれまで、こうしたSkillは「Claude Code独自の便利機能」のようなものだと思っていました。
しかし最近調べてみると、SKILL.mdを中心としたAgent Skillsというオープンな標準形式が存在し、Claude CodeだけでなくOpenAI CodexやGitHub Copilotなど、複数のAIエージェントで利用できる仕組みになっていることを知りました。
さらに興味深かったのが、Agent Skillsでは単に指示をファイルへ切り出すだけではなく、「Progressive Disclosure（段階的開示）」という考え方によってコンテキストを管理していることです。
この記事では、私自身がAgent Skillsについて調べて理解した内容を整理します。
Agent Skillsとは
Agent SkillsはAIエージェントに特定の知識や作業手順を追加するための仕組みです。
基本となる構成は非常にシンプルです。
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
必須なのはSKILL.mdだけです。
scripts/、references/、assets/は必要に応じて追加します。
たとえば技術記事を書くSkillであれば、次のような構成が考えられます。
technical-blog-writing/
├── SKILL.md
├── references/
│ ├── article-structure.md
│ └── writing-rules.md
├── scripts/
│ └── validate-article.py
└── assets/
└── article-template.md
SKILL.mdには記事を書くための基本的な手順を書く。
より細かい文章ルールはreferences/へ置く。
記事をチェックする処理が必要であればscripts/へ置く。
記事作成時に使用するテンプレートはassets/へ置く。
このように、Skillをひとつの小さなパッケージとして管理できます。
SKILL.mdがSkillの入口になる
Skillの中心となるのがSKILL.mdです。
最低限、YAML Frontmatterとしてnameとdescriptionを定義します。
---
name: technical-blog-writing
description: 技術ブログの記事を作成するときに使用する。
---
# Technical Blog Writing
## Workflow
1. 記事のテーマを確認する
2. 想定読者を整理する
3. 記事構成を作成する
4. 本文を書く
5. 内容をレビューする
nameはSkillの識別子です。
そして重要なのがdescriptionです。
Agent Skillsでは、エージェントが「このSkillを使うべきか」を判断するためにdescriptionを利用します。
そのため、
description: ブログを書くためのSkill
のような曖昧な説明よりも、
description: 技術ブログの記事を新規作成・レビュー・リライトするときに使用する。
のように「何をするSkillなのか」「いつ使うのか」を明確にした方が、適切にSkillを呼び出しやすくなります。
ここまでは、Claude CodeでSkillを使ったことがあれば比較的イメージしやすいと思います。
私がAgent Skillsを調べて特に面白いと感じたのは、この先です。
すべてのSkillを最初から読み込むわけではない
AIエージェントにルールをたくさん持たせようとすると、ひとつ問題が出てきます。
コンテキストが大きくなってしまうことです。
仮に次のSkillを持っていたとします。
skills/
├── technical-blog-writing/
├── code-review/
├── database-design/
├── api-design/
├── testing/
├── security-review/
└── refactoring/
もしセッション開始時にこれらすべてのSKILL.mdを読み込んでいたらどうなるでしょうか。
技術記事を書きたいだけなのに、
- DB設計ルール
- API設計ルール
- テストルール
- セキュリティルール
までコンテキストへ入ってしまいます。
Skillを増やすほどコンテキストが膨らみ、AIに渡せる情報量を無駄に消費してしまいます。
Agent Skillsでは、この問題に対して**Progressive Disclosure（段階的開示）**という考え方が使われています。
Progressive Disclosure（段階的開示）とは
Agent Skillsでは、大きく3段階に分けて情報を読み込みます。
Level 1
name + description
↓
Level 2
SKILL.md
↓
Level 3
scripts / references / assets
Level 1：Skillの存在だけを知る
最初からSkillのすべてを読み込むわけではありません。
基本的にはそれぞれのSkillの
name
description
といったメタデータだけを使って、「どんなSkillが存在するのか」をエージェントへ知らせます。
公式仕様では、この段階の情報量はSkillあたりおおよそ50〜100トークン程度を想定しています。
たとえば、
name: technical-blog-writing
description: 技術ブログの記事を作成・レビューするときに使用する
という情報だけを最初に知っておきます。
この段階では、まだ記事作成ルールの詳細までは読み込んでいません。
Level 2：必要になったらSKILL.mdを読む
ユーザーから、
Agent Skillsについて技術記事を書いて
と依頼されたとします。
エージェントは登録されているSkillのdescriptionを確認して、
technical-blog-writingが使えそう
と判断します。
そこで初めて、
technical-blog-writing/SKILL.md
を読み込みます。
つまり、
Skill一覧を知る
↓
タスクを確認する
↓
必要なSkillを判断する
↓
SKILL.mdを読む
という流れです。
すべてのSkillを常時読み込む必要がありません。
Agent Skillsの仕様では、SKILL.mdは500行未満、5,000トークン未満程度に抑え、より詳細な情報については別ファイルへ分割することが推奨されています。
Level 3：さらに必要な情報だけ読む
ここでもう一段階あります。
SKILL.mdから参照する情報についても、すべて最初から読み込む必要はありません。
たとえば次の構成です。
technical-blog-writing/
├── SKILL.md
└── references/
├── introduction.md
├── seo.md
├── code-example.md
└── review.md
そしてSKILL.mdに、
SEOを考慮する場合は
references/seo.mdを参照する。
コード例を含める場合は
references/code-example.mdを参照する。
と書いておきます。
今回の記事でコード例が必要なければ、code-example.mdを読む必要はありません。
つまり、
Skillを選ぶ
↓
SKILL.mdを読む
↓
必要なreferenceだけ読む
と、必要性に応じて情報を少しずつ開示していきます。
これがProgressive Disclosureです。
個人的にはAgent Skillsについて調べる中で最も重要だと感じた考え方でした。
referencesは「SKILL.mdを太らせない」ために使える
references/には、Skillを実行するために必要な詳細資料を配置します。
たとえば、
references/
├── coding-rules.md
├── api-specification.md
├── architecture.md
└── examples.md
といった形です。
ここで重要なのは、単にファイルを分割することではありません。
必要な場面でだけ読み込める単位に情報を分割することです。
たとえばAWS、GCP、Azureに対応したデプロイSkillなら、
cloud-deploy/
├── SKILL.md
└── references/
├── aws.md
├── gcp.md
└── azure.md
とできます。
AWSへデプロイする場合、
references/aws.md
だけを読めばよく、GCPやAzureの情報をコンテキストへ入れる必要はありません。
OpenAIが公開しているCodex向けSkill Creatorでも、このようにドメインごとにreferenceを分離し、必要なものだけ読む構造が紹介されています。
これは単なるファイル整理というより、コンテキスト設計そのものだと思います。
scriptsは「説明する」代わりに「実行する」
scripts/には、エージェントが実行できるコードを配置します。
scripts/
├── validate.py
├── extract.sh
└── generate.js
たとえばコードレビューSkillで、
package.jsonを解析して依存関係を確認する
という処理が毎回必要だったとします。
これを長いプロンプトでAIへ説明するより、
scripts/analyze-dependencies.py
として処理を実装しておいた方が確実です。
SKILL.mdから、
依存関係を確認するときは
scripts/analyze-dependencies.pyを実行する。
と指示できます。
Agent Skillsの公式ドキュメントでも、scripts/はPython、Bash、JavaScriptなどの実行可能なコードを配置する場所として定義されています。
ここにはもうひとつメリットがあります。
処理内容を大量のテキストとしてコンテキストへ読み込ませる必要がありません。
「このスクリプトを実行する」という指示だけ持っていれば、決定的な処理はコード側へ任せられます。
AIに判断させる部分と、プログラムに処理させる部分を分離できるわけです。
assetsは出力に使うファイルを置く
assets/は少し役割が違います。
こちらには、主に最終的な成果物を作る際に利用するファイルを配置します。
たとえば、
assets/
├── article-template.md
├── logo.png
├── presentation-template.pptx
└── frontend-template/
といったものです。
CodexのSkill Creatorでも、assets/は必ずしもコンテキストへ読み込む情報ではなく、最終成果物の作成時にコピーしたり加工したりするためのリソースとして整理されています。
この違いを整理すると、
SKILL.md
→ 作業手順
references/
→ 判断するために読む情報
scripts/
→ 実行する処理
assets/
→ 成果物を作るために使う素材
と考えると分かりやすいです。
CLAUDE.mdやAGENTS.mdに全部書くのとは何が違うのか
ここまで理解すると、以前私が行っていたAIエージェントのコンテキスト管理についても考え方が変わりました。
Claude CodeであればCLAUDE.md、CodexであればAGENTS.mdなどにプロジェクトルールを書くことができます。
もちろん、
このプロジェクトではTypeScriptを使用する
pnpmを使用する
テストにはVitestを使用する
といった、ほぼすべての作業で必要になる情報は常時読み込ませる価値があります。
一方、
技術記事を書くときのルール
DB設計するときのチェックリスト
Reactコンポーネントをレビューするときの手順
リリースするときの確認事項
まで常時コンテキストへ入れる必要があるかというと、そうではありません。
そこで、
常に必要
↓
CLAUDE.md / AGENTS.mdなど
特定の作業だけ必要
↓
Skills
Skillの中でも詳細情報
↓
references
機械的に処理できる
↓
scripts
成果物として利用する
↓
assets
という切り分けができます。
この考え方を使うことで、「AIにたくさん情報を与える」のではなく、必要なタイミングで必要な情報だけを与える設計ができます。
Claude CodeだけではなくCodexやGitHub Copilotでも使える
私がAgent Skillsについて一番認識を改めたのがここでした。
もともと私はClaude CodeのSkillとして認識していました。
しかしAgent Skillsは現在、特定のAIエージェントだけに閉じた仕組みではありません。
Agent Skillsの公式Quickstartでは、同じSkillをClaude CodeやOpenAI Codexなどの互換エージェントで利用できるオープン形式として説明されています。
GitHub CopilotもAgent Skillsを正式にサポートしており、プロジェクト内ではたとえば次の場所からSkillを利用できます。
.github/skills/
.claude/skills/
.agents/skills/
GitHub CopilotではVS CodeのAgent mode、Copilot CLI、Copilot coding agentなどから利用できます。
OpenAI CodexにもAgent Skillsの仕組みがあり、SKILL.md、scripts/、references/、assets/という構成が使われています。
つまり、
Claude Code専用Skill
ではなく、
Agent Skillsという共通形式
↓
Claude Code
Codex
GitHub Copilot
その他の対応エージェント
という捉え方の方が近いです。
もちろん、Skillを置くディレクトリや独自のメタデータ、呼び出し方法などは各ツールで異なります。
そのため、「ひとつ作ればすべてのツールで完全に同じ動作をする」という意味ではありません。
それでも、Skillの中心となる
SKILL.md
scripts/
references/
assets/
という構成や、「必要なSkillを必要なときだけ読み込む」という考え方を共有できるのは大きなメリットだと思います。
SubagentとSkillは役割が違う
Claude Codeを使っていると、Skillと一緒にSubagentもよく登場します。
両者は似ているように見えますが、役割が異なります。
Skillは、
どうやって仕事をするか
を定義するものです。
たとえば、
コードレビューでは何を見るか
技術記事をどういう順序で書くか
DB設計では何を確認するか
といった「知識や手順」を持たせます。
一方、Subagentは、
誰に仕事を任せるか
に近い仕組みです。
メインのエージェントから別コンテキストのエージェントへタスクを委譲し、専門的な作業を任せます。
たとえば、
メインエージェント
↓
調査Subagent
↓
コードレビューSubagent
↓
テストSubagent
と役割を分けられます。
GitHub Copilotのドキュメントでも、Agent Skillsは「必要に応じて読み込む指示・スクリプト・リソース」、Subagentは「メインエージェントから委譲された作業を独立したコンテキストで処理するエージェント」と区別されています。
整理すると、
Skill
= 専門知識・手順
Subagent
= 専門作業を担当するエージェント
です。
さらに、
Subagent
↓
Skillを使用
という組み合わせも考えられます。
この2つを区別できるようになってから、AIエージェントの構成を考えやすくなりました。
Skillは「巨大なプロンプトファイル」ではない
以前の私はSkillについて、
毎回書いているプロンプトをファイル化したもの
くらいに考えていました。
もちろん、それだけでも便利です。
しかしAgent Skillsの仕様を調べてみると、それだけではないことが分かりました。
どのSkillが存在するか
↓
今のタスクに必要なSkillは何か
↓
SKILL.mdを読む
↓
さらに必要なreferenceだけ読む
↓
必要ならscriptを実行する
↓
assetを使って成果物を作る
という、一連の情報取得フローそのものが設計されています。
つまりAgent Skillsは、
AIに専門知識を追加する仕組みであると同時に、コンテキストを効率的に管理する仕組みでもある
と考えられます。
Skillを増やしてもコンテキストを圧迫しにくい
Progressive Disclosureを理解すると、「Skillをたくさん作るとコンテキストが大きくなるのではないか」という疑問にも答えが見えてきます。
仮に20個のSkillがあっても、最初から20個分のSKILL.mdをすべて読むわけではありません。
最初に必要なのは基本的に、
Skill A：名前 + description
Skill B：名前 + description
Skill C：名前 + description
...
というカタログです。
実際に必要になったSkillだけを読み込みます。
さらにSkill内部の情報も分割できます。
SKILL.md
↓
必要ならreference A
↓
必要ならscript B
と展開できます。
「AIのコンテキストを節約するために情報を削る」のではなく、
情報は保持したまま、必要になるまで読み込まない
という設計になっているところが面白いと感じました。
今後は「プロンプトを書く」より「コンテキストを設計する」が重要になりそう
生成AIを使い始めた頃は、
どういうプロンプトを書けば良い回答が出るか
ということを考えることが多かったと思います。
しかしClaude CodeやCodexのようなAIエージェントを開発へ組み込んでいくと、それだけでは足りなくなります。
必要になるのは、
何を常時読み込ませるか
何をSkillへ分離するか
何をreferenceへ逃がすか
何をscriptとして決定的に処理するか
どこまでをSubagentへ任せるか
という設計です。
これはかなりソフトウェア設計に近い考え方だと感じています。
すべてをひとつのファイルへ書くのではなく、
責務を分離する
必要なものだけ参照する
再利用可能な単位へ切り出す
という考え方は、普段のプログラミングとよく似ています。
Agent Skillsを知ったことで、私はSkillを単なる「AI向けの便利な指示ファイル」ではなく、AIエージェントに渡すコンテキストを構造化する仕組みとして見るようになりました。
まとめ
Agent Skillsについて調べて、特に印象に残ったポイントは次の通りです。
- Skillは
SKILL.mdを中心としたオープンな形式 - Claude CodeだけでなくCodexやGitHub Copilotなどでも利用されている
descriptionによってエージェントが使用するSkillを判断する- Progressive Disclosureによって段階的に情報を読み込む
- 詳細資料は
references/へ分離できる - 決定的な処理は
scripts/へ分離できる - テンプレートなどの成果物用リソースは
assets/へ配置できる - SkillとSubagentには「知識」と「実行主体」という役割の違いがある
特に重要なのはProgressive Disclosureだと思います。
Metadata
↓
SKILL.md
↓
Resources
と段階的に情報を読み込むことで、多くの専門知識を用意しながら、不要な情報でコンテキストを埋めることを避けられます。
これまでは「AIに何を指示するか」というプロンプトの書き方に目が向きがちでした。
しかしAIエージェントを本格的に使うのであれば、これからは、
「どの情報を、どのタイミングで、どこからAIへ渡すか」
というコンテキスト設計も重要になっていきそうです。
Agent Skillsは、そのためのひとつの標準的な仕組みとして、今後さらに活用していきたいと思います。
参考資料
- Agent Skills — Overview / Specification
- Agent Skills — How to add skills support to your agent
- Agent Skills — Best practices for skill creators
- GitHub Docs — Adding agent skills for GitHub Copilot
- OpenAI Codex — Agent Skills / Skill Creator
