Agent Skills オープン標準仕様を読み解く — agentskills.ioが目指すエージェント間スキル共有の世界

はじめに

私はClaude Codeのスキルを20個以上作成し、日常的に運用しています。skill-stocktakeによる棚卸しも定期的に実施しており、スキルの品質管理には一定の知見があります。

以前「Skillsを50個運用して気づいた — 増やすほど生産性が下がるパラドックス」という記事を書きました。スキルは便利ですが、増えるほど管理コストが膨らみ、生産性が下がり始めるという問題提起です。

そんな中、2025年12月にAnthropicがAgent Skillsをオープン標準として公開しました。agentskills.ioとして仕様が整備され、2026年4月時点で30以上のコーディングエージェントが対応しています。この記事では仕様の全体像と技術的な詳細を読み解きます。

なぜ標準仕様が必要なのか

現状、コーディングエージェントごとにスキルの定義がバラバラです。

Claude Codeでは .claude/skills/（AIが自動選択するスキル）と .claude/commands/（ユーザーがスラッシュコマンドで呼び出す）の2種類があります。CursorにはCursor Rulesがあります。GitHub CopilotにはCustom Instructionsがあります。それぞれ書式も配置場所も異なります。

これが引き起こす問題は明確です。

• コーディングエージェントを乗り換えるたびにスキルを書き直す必要がある
• チームで複数のコーディングエージェントを使う場合、同じスキルを二重管理する
• スキルを公開・共有しても、特定のコーディングエージェントのユーザーにしか届かない

MCPがツール接続の標準化を実現したように、スキル定義にも共通フォーマットが求められていました。Agent Skillsはこの課題に対する回答です。

Agent Skills仕様の全体像

agentskills.ioで公開されている仕様は、驚くほどシンプルです。

スキルとは「SKILL.mdを含むフォルダ」です。最小構成はこれだけです。

skill-name/
├── SKILL.md          # 必須: メタデータ + 指示
├── scripts/          # 任意: 実行可能なコード
├── references/       # 任意: 参考ドキュメント
├── assets/           # 任意: テンプレートやリソース
└── ...

SKILL.mdはYAMLフロントマターとMarkdown本文で構成されます。特別なDSLやスキーマ定義は不要です。Markdownが書ければスキルが作れます。

この設計は意図的です。参入障壁を下げることで、エコシステムの成長を優先しています。

MCPとの関係性

Agent SkillsとMCPは競合ではなく、補完関係にあります。

MCPは「エージェントが外部ツールをどう呼び出すか」を標準化します。データベースへの接続、APIの呼び出し、ファイル操作などです。接続のプロトコルです。

Agent Skillsは「エージェントが何をどう実行するか」を標準化します。手順書、ベストプラクティス、ドメイン知識の定義です。知識のフォーマットです。

具体例で考えます。「PDFから表を抽出してCSVに変換する」というタスクがあるとします。MCPはPDF操作ツールへの接続方法を定義します。Agent Skillsは「どのツールをどの順序で使い、エッジケースにどう対処するか」を定義します。

両者を組み合わせることで、エージェントは「何に接続できるか」だけでなく「どう仕事をすべきか」も理解できます。

仕様の技術的詳細

フォルダ構造と配置場所

スキルの配置場所は2つのスコープで管理されます。

スコープ	パス	用途
プロジェクト	<project>/.agents/skills/	リポジトリ固有のスキル
ユーザー	~/.agents/skills/	全プロジェクト共通のスキル

.agents/skills/ はコーディングエージェント間で共有するための共通パスです。これに加えて、各コーディングエージェント固有のパスも走査されます。

<project>/.claude/skills/     # Claude Code固有
<project>/.cursor/skills/     # Cursor固有
<project>/.agents/skills/     # 共通（推奨）

プロジェクトレベルのスキルがユーザーレベルより優先されます。同名のスキルがある場合、プロジェクト側が勝ちます。

SKILL.mdの構造

SKILL.mdはYAMLフロントマターとMarkdown本文の2部構成です。

---
name: pdf-processing
description: PDFからテキストを抽出し、フォーム入力やファイル結合を行う。PDF関連のタスクで使用。
license: Apache-2.0
compatibility: Python 3.14+とuvが必要
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(python:*) Read
---

# PDF Processing

## いつ使うか
ユーザーがPDFファイルを操作する必要があるとき...

## テキスト抽出の手順
1. pdfplumberを使って...

フロントマターの各フィールドを見ていきます。

name（必須）はスキルの識別子です。小文字英数字とハイフンのみ。64文字以内。親ディレクトリ名と一致する必要があります。この制約により、ファイルシステム上の位置とスキル名が常に対応します。

description（必須）はスキルの説明です。1024文字以内。何ができるか、いつ使うかの両方を含めます。エージェントはこのフィールドだけを見てスキルの選択を判断するため、記述の質が重要です。

licenseは任意ですが、公開スキルでは指定が推奨されます。compatibilityは動作環境の要件を記述します。metadataは任意のキー値ペアです。

allowed-toolsは実験的フィールドです。スキルが使用するツールを事前承認リストとして宣言します。

Markdown本文には形式の制約がありません。ステップバイステップの手順、入出力の例、エッジケースの対処法など、エージェントの実行に役立つ内容を自由に記述します。

リソース定義

scripts/にはエージェントが実行するコードを配置します。Bash、Python、JavaScriptが一般的です。自己完結型にするか、依存関係を明記します。

references/には参照用ドキュメントを配置します。ドメイン固有の知識、APIリファレンス、テンプレートなどです。ファイルは小さく分割します。エージェントはオンデマンドで読み込むため、1ファイルが小さいほど効率的です。

assets/にはテンプレート、画像、スキーマなどの静的リソースを配置します。

スキルの発見メカニズム（Progressive Disclosure）

Agent Skillsの設計で最も巧みな部分がProgressive Disclosureです。3段階でコンテキストを管理します。

第1段階はカタログです。セッション開始時に全スキルのnameとdescriptionだけを読み込みます。1スキルあたり約50〜100トークンです。20個あっても1000〜2000トークンで収まります。

第2段階はインストラクションです。タスクがスキルの説明と合致したとき、SKILL.mdの本文全体を読み込みます。推奨は5000トークン以内です。

第3段階はリソースです。本文中で参照されたスクリプトやドキュメントを、必要になったタイミングで個別に読み込みます。

この設計により、100個のスキルがインストールされていても、起動時のコストは最小限です。使われないスキルはカタログのみ。使われるスキルだけが詳細を読み込まれます。

コンテキスト圧縮時にスキル内容が失われないよう、スキルの出力を保護する仕組みも仕様に含まれています。

対応コーディングエージェントの状況

2026年4月時点で、以下のコーディングエージェントがAgent Skillsに対応しています。

主要コーディングエージェント:

• Claude Code / Claude（Anthropic）
• OpenAI Codex
• Gemini CLI（Google）
• GitHub Copilot / VS Code（Microsoft）
• Cursor
• Kiro（AWS）

その他の対応コーディングエージェント:

• Junie（JetBrains）、Amp、Goose（Block）、Roo Code
• OpenHands、OpenCode、Letta、Firebender
• Mux（Coder）、Autohand、Factory、TRAE（ByteDance）
• Databricks、Snowflake、Spring AI
• Laravel Boost、Qodo、Mistral Vibe

30を超えるコーディングエージェントが対応済みです。MCPの普及速度と同様、事実上の標準として定着しつつあります。

自分のスキルを標準仕様に準拠させる方法

既存のClaude Codeスキルを標準仕様に移行する手順を示します。

1. フォルダ構造の整理

Claude Codeの.claude/commands/にあるMarkdownファイルを、フォルダ構造に変換します。

変換前:

.claude/commands/deploy.md

変換後:

.agents/skills/deploy/
├── SKILL.md
└── scripts/
    └── deploy.sh

2. SKILL.mdのフロントマター追加

既存のMarkdownファイルの先頭にフロントマターを追加します。

---
name: deploy
description: 本番環境へのデプロイ手順を実行する。デプロイ、リリース、公開の際に使用。
---

descriptionには「何ができるか」と「いつ使うか」の両方を書きます。エージェントがスキルを選ぶ判断材料になるためです。

3. 長いスキルの分割

500行を超えるSKILL.mdは分割を検討します。詳細なリファレンスはreferences/に、実行スクリプトはscripts/に移動します。

4. バリデーション

公式のリファレンスライブラリで検証します。

npx skills-ref validate ./my-skill

5. コーディングエージェント間の共有配置

.agents/skills/に配置すれば、対応する全コーディングエージェントからスキルが利用可能になります。Claude Code固有の.claude/skills/にも引き続き配置できます。

以前の記事で指摘した「スキルの負債化」問題に対して、標準仕様への準拠は一つの解決策になります。フォーマットが統一されることで、棚卸しや品質管理の基準が明確になるためです。

まとめ

Agent Skillsの仕様を読み解いた所感をまとめます。

仕様は意図的にシンプルです。Markdownとフォルダという誰もが扱えるプリミティブで構成されています。DSLもスキーマも不要です。この低い参入障壁が、30以上のコーディングエージェント対応という急速な普及を支えています。

Progressive Disclosureの設計は実用的です。カタログ、インストラクション、リソースの3段階で、コンテキストウィンドウを効率的に使います。MCPとの補完関係も明確で、接続と知識という異なるレイヤーをそれぞれが担当します。

日常的にスキルを作成・運用する立場から言えば、標準仕様の最大の恩恵は「一度書けばどこでも動く」ことです。Claude CodeからCursorに切り替えても、同じスキルがそのまま使えます。チーム内でコーディングエージェントが混在していても、スキルの共有が可能になります。

スキルの負債化リスクは依然として残ります。しかし、標準仕様があることで、棚卸しの基準、品質の指標、共有のインフラが整います。今後はスキルのレジストリやバージョン管理の仕組みが求められるでしょう。

Agent Skillsの標準化は、AIエージェントの「知識のポータビリティ」という未解決の課題に対する、現時点で最も現実的な回答です。