## SKILL.md とは？

SKILL.md は通常 `/skill.md` で配信される単一の Markdown ファイルで、AI エージェントにサービスの使い方を伝えます。ファイルは `name` と `description` の 2 つのフィールドを宣言する YAML フロントマターから始まり、続いてエンドポイント、認証モデル、エージェントが動作するために必要なリクエスト形式を文書化する自由形式の Markdown が続きます。

仕様は [agentskills.io](https://agentskills.io/specification) で公開されており、Anthropic の Claude Code、OpenAI Codex、Cursor、GitHub Copilot、Microsoft の Agent Framework によってベンダー横断の規約として採用されています。SKILL.md ファイルは、エージェントが「このサイトを見つけた」から「呼び出し方を知っている」へ移行できる最小のアーティファクトです。

## SKILL.md が重要な理由

LLM エージェントは人間と同じオンボーディングコストに直面します — 未知のサービスが何のためにあり、どう正しく呼び出すかを把握することです。人間にはクイックスタートを書き、エージェントには SKILL.md を書きます。フロントマターの `name` はエージェントが内部登録できる安定した識別子を提供し、`description` はツールリストとプランナーに表示されるもので、本体はプレイブックです。

代替手段 — エージェントがあなたの完全なドキュメントサイト、OpenAPI スキーマ、ホームページを読んで同じ情報を再構築すること — は遅く、コストがかかり、損失があります。SKILL.md はオンボーディングを 1 回のフェッチと数百トークンに縮めます。

## SKILL.md の仕組み

プロトコルハンドシェイクはありません。エージェントは `/skill.md` をリクエストし、YAML フロントマターから `name` と `description` を解析し、仕様の正規表現で名前を検証し、Markdown 本体を指示として読みます。

最小限の有効な SKILL.md：

```markdown
---
name: scan-url
description: 任意の URL の AI エージェント対応度をスキャンし、0-100 のスコアを返します。ユーザーがサイトのエージェント対応度を尋ねたり、サイト間でプロトコルサポートを比較したいときに使用してください。
---

# Agent Readiness Scan

エージェント向け JSON レスポンスには `GET /api/v1/scan?url={url}` を使用します。

## エンドポイント

- `GET /api/v1/scan?url={url}` — エージェント向けのフラット JSON
- `GET /api/scan?url={url}` — 完全な HTML レポート（人間向け）
- `GET /api/badge?url={url}` — SVG バッジ

## 認証

なし。すべて無料。

## 例

`curl https://agentgrade.com/api/v1/scan?url=https://example.com`
```

これが全ての表面です。このファイルを見つけたエージェントは、初回試行であなたのサービスを正しく呼び出すのに十分な情報を持っています。

## SKILL.md と他のエージェント対応ファイルの比較

| ファイル | 誰が配信 | 何に答えるか | 形式 |
|---|---|---|---|
| **SKILL.md** | サービス | *このサービスをどう使う？* | Markdown + フロントマター |
| **[OpenAPI](/kb/ja/openapi)** | サービス | *どんなエンドポイントがあり、スキーマは？* | JSON/YAML |
| **[MCP](/kb/ja/mcp) マニフェスト** | MCP サーバー | *JSON-RPC でどんなツールを公開？* | JSON-RPC |
| **`ai-plugin.json`** | サービス | *ChatGPT プラグイン形式（レガシー）のメタデータ* | JSON |
| **[llms.txt](/kb/ja/llms-txt)** | サービス | *このサイトは何か、散文で* | Markdown |

SKILL.md は「プレイブック」層、OpenAPI は「スキーマ」層です。両方を構成できます。SKILL.md はエージェントにいつどのエンドポイントを呼ぶか伝え、OpenAPI は正式なパラメータスキーマを提供します。

`ai-plugin.json` は SKILL.md より前で、OpenAI が廃止したオリジナルの ChatGPT プラグイン形式に結びついていました。SKILL.md は現代的なベンダー横断の後継です。

## フロントマターの検証

agentskills.io 仕様は 2 つのフィールドに厳格です：

- **`name`** — 1-64 文字、小文字英数字とハイフン 1 つ。`^[a-z0-9]+(-[a-z0-9]+)*$` に一致する必要があります。先頭、末尾、連続するハイフンは不可。
- **`description`** — 1-1024 文字。エージェントが実行する動詞で始めます。説明はツールピッカーとプランナーの推論に表示されます。

仕様に準拠したエージェントとスキャナーは、不正なフロントマターを持つファイルを拒否します。

## SKILL.md を採用したのは誰か

仕様は 2025 年に単一ベンダー規約から相互運用可能な標準へと移行しました：

- **Claude Code** ([docs.claude.com/en/docs/claude-code/skills](https://docs.claude.com/en/docs/claude-code/skills)) — Anthropic のコーディングエージェントはローカルディレクトリから SKILL.md ファイルを読み込みます。
- **OpenAI Codex** — エージェントスキル定義に同じ形式を採用。
- **Cursor** — プロジェクトワークスペースから SKILL.md を読み、エージェントのインラインガイダンスに使用。
- **GitHub Copilot** — リポジトリレベルのエージェント指示に同じフロントマター規約を尊重。
- **Microsoft Agent Framework** — ベンダー横断実装は agentskills.io 仕様に従います。

形式は単に YAML フロントマター付き Markdown なので、採用コストはほぼゼロです。

## SKILL.md をサイトに追加する方法

1. **名前を選ぶ。** 動詞-名詞句、小文字ハイフン、64 文字未満。
2. **説明を書く。** 2 文。文 1: エージェントが達成すること。文 2: いつ使うか。
3. **本体を書く。** HTTP 動詞付きエンドポイント、認証モデル、コピペ可能な curl 例 1 つ。1 画面分のテキストに収めます。
4. **`/skill.md` で配信。** 静的ファイル。`Content-Type: text/markdown`。
5. **llms.txt または `/.well-known/` からリンク。** オプションだが推奨。

有効な SKILL.md と [OpenAPI](/kb/ja/openapi) 仕様を持つサイトは、何も知らずに到着するエージェントに対して十分に整備されています。

## スキャナーがフラグを立てる一般的なエラー

- **フロントマター区切り文字の欠落** — ファイルが `---` で始まらない。
- **無効な `name`** — 大文字、アンダースコア、先頭/末尾のハイフン。
- **説明が短すぎる** — 1 文字未満（空）またはエージェントに信号がないほど短い。80-200 文字を目指してください。
- **説明が長すぎる** — 1024 文字超。詳細を本体に移動してください。
- **パスが間違っている** — `/skills.md`（複数形）、`/.well-known/skill.md`、または `/skill/index.md` で配信。仕様はドキュメントルートの `/skill.md` です。
- **content-type が間違っている** — CMS が Markdown を自動レンダリングするため `text/html` として配信。生の `text/markdown` または `text/plain` を配信してください。

## FAQ

**SKILL.md は Anthropic の「Claude Skills」と同じですか？**
ディスク上の形式は同じです。「Claude Skills」は SKILL.md ファイルを消費する機能の Anthropic の製品名で、形式自体はベンダー横断の agentskills.io 仕様です。

**SKILL.md と OpenAPI の両方が必要ですか？**
API があるなら両方を配信してください。SKILL.md は「どう使う？」を散文で答え、OpenAPI は「正確なスキーマは？」を形式的に答えます。

**`/skills.json` を置き換えたのは何ですか？**
`/skills.json` は標準が存在する前の、手作りの初期マニフェスト形式でした。「使い方」層は SKILL.md に、有料エンドポイントの宣言は OpenAPI の `x-payment-info`（[OpenAPI](/kb/ja/openapi) 参照）に置き換えられました。AgentGrade は `/skills.json` をスコアしません。

**SKILL.md ファイルはどこに置くべきですか？**
ドキュメントルートの `/skill.md` です。一部のエージェントはフォールバックとして `/.well-known/skill.md` もプローブします。

**サイトは複数の SKILL.md ファイルを持てますか？**
規約はオリジンあたり 1 つの `/skill.md` です。

**SKILL.md は [MCP](/kb/ja/mcp) を置き換えますか？**
いいえ — 異なる質問に答えます。SKILL.md はエージェントに既存のエンドポイント経由で HTTP サービスを使う方法を伝えます。MCP は持続的接続でエージェントがサーバーをツールとして呼び出す JSON-RPC インターフェースを定義します。

**AgentGrade は OpenAPI なしで SKILL.md を公開するサイトにペナルティを課しますか？**
いいえ。SKILL.md はそれ自体が肯定的な信号です。

**エージェントは実際にこのファイルを読みますか？**
Claude Code、Codex、Cursor、Copilot は今日ワークスペース内の SKILL.md ファイルを読みます。ブラウジングエージェントは `/llms.txt` や `/openapi.json` と並んで `/skill.md` を発見ハンドシェイクの一部としてますますプローブしています。

## 仕様の成熟度

**ベンダー横断標準。** [agentskills.io](https://agentskills.io/specification) で定義。Claude Code、OpenAI Codex、Cursor、GitHub Copilot、Microsoft Agent Framework によって採用されています。

## 詳細

- [agentskills.io](https://agentskills.io/specification) — 仕様
- [Claude Code skills ドキュメント](https://docs.claude.com/en/docs/claude-code/skills) — Anthropic の採用
- [OpenAPI](/kb/ja/openapi) — 付属のスキーマ層
- [MCP](/kb/ja/mcp) — JSON-RPC ツールサーバーの代替