メインコンテンツまでスキップ

SKILL.md：エージェント横断のオープン標準

中級

数年間、コーディングエージェントは自分専用のファイルを持っていた — .cursorrules、CLAUDE.md、Codex のシステムプロンプト、Gemini の instructions、他にも十数種類。そして Anthropic は静かに、自社内の Skills 形式をオープン仕様にした — 48 時間以内に、世界中の主要エージェントが互いのファイルを読むようになった。今日、code-reviewer/ というひとつのディレクトリに SKILL.md を置けば、Claude Code、Codex CLI、ChatGPT、Gemini CLI、Junie、Kiro、Goose、Cursor で無改変で動く。エージェント業界が「共通プラグ」に最も近づいた瞬間だ。

このページは実践的なフィールドガイドである：標準の実際のバイトレベルの中身、100 個のスキルインストールを安くする 1 つの巧妙な仕掛け（progressive disclosure）、触った瞬間に可搬性を壊すフィールド、正直なセキュリティ像、そして今日そのままコピペで出荷できる可搬スキルの完全なサンプル。

What you'll learn
  • SKILL.md がファイル形式レベルで何か理解する — 必須フィールド、任意フィールド、ディレクトリ配置
  • progressive disclosure を理解する：なぜ 100 個のスキルが起動時に約 10K トークンで済み、本体 100 倍にならないのか
  • エージェント間の可搬性を静かに壊す、正確なベンダー拡張を把握する
  • Claude Code、Codex CLI、Gemini CLI で無改変で動くスキルを書く
  • どのマーケットプレイスからでもスキルをインストールする前に、セキュリティのトレードオフを正直に評価する

標準の実体​

マーケティングを剥がすと、Agent Skills オープン標準は頭の中に収まるほど小さい：

  • スキルの name と一致する名前の ディレクトリ
  • その中の 必須の SKILL.md — YAML frontmatter に続いて Markdown 本体
  • 任意の兄弟ディレクトリ：scripts/（スキルが実行できる実行ファイル）、references/（オンデマンドで取り込むドキュメント）、assets/（テンプレート、画像、プロンプトファイル）、そして後から追加された agents/（opt-in のベンダー固有設定）

これで表面積のすべてだ。2 つの必須 frontmatter フィールドが仕事のほとんどをやる：

  • name — 最大 64 文字、lowercase-with-hyphens、親ディレクトリと一致必須
  • description — 最大 1,024 文字、エージェントが 現在のタスクにこのスキルをロードするかどうか を決めるために使う文

その他すべて — license、compatibility、metadata、まだ実験的な allowed-tools — は任意で、理解しないツールは安全に無視する。本体は Markdown で、コミュニティの慣習は約 5,000 トークン以下に保つこと。実世界のスキルはほぼそうしている：最大のマーケットプレイスでのスキル中央値は約 1,414 トークン、90% が 3,935 トークン 以下だ。

1 つの巧妙な仕掛け：progressive disclosure​

SKILL.md がスケールで動く理由は、ファイル形式ではなく、エージェントが どうロードするか にある。すべての適合エージェントは 3 段のティアを実装している：

Guided walkthrough1 of 3
  1. エージェントは skills ディレクトリを走査し、すべての SKILL.md の frontmatter だけを読む。1 スキル当たり約 100 トークン。100 個インストールしても、最初のプロンプト前に約 10K トークン — 1 通の長いシステムメッセージより安い。

これが description を厳しく制限し、一級市民として扱う理由だ：スキルを 起動するかどうか を選ぶときにモデルが見る唯一のテキストなのだ。曖昧な description は、「動くはずの」スキルが決して発火しない最大の理由だ。

:::tip description は最後に書き、そして書き直す スキルの本体が固まったら、description を広告コピーとして扱おう。仕事はただ 1 つ：このスキルが所有すべきタスクの形をモデルに認識させることだ。「Reviews pull requests」はダメ。「PR の diff を、ロジックバグ、テスト漏れ、プロジェクト規約違反についてレビューする。ユーザーが review / code review / 'look at this PR' を要求したときはいつでも使う」は良い。 :::

万能ディレクトリ​

すべての適合エージェントが同じ配置を期待する。この配置ならどこでも動く：

code-reviewer/
├── SKILL.md          # 必須 — エージェントが読む指示
├── scripts/          # 任意 — スキルが呼び出せる実行ファイル
│   └── run-linters.sh
├── references/       # 任意 — オンデマンドで引く長文ドキュメント
│   └── style-guide.md
├── assets/           # 任意 — テンプレート、プロンプトファイル、スニペット
│   └── pr-comment-template.md
└── agents/           # 任意 — ベンダー固有、opt-in のみ
    └── openai.yaml   # Codex 以外のエージェントは無視

agents/ サブディレクトリは標準の安全弁だ：ベンダーがポータブルなコアを汚さずに拡張を出荷できる。agents/openai.yaml にあるファイルは Codex 固有で、他のすべてのエージェントは単純に無視する。追加の力が必要なときに使い、可搬性を犠牲にすると認識すること。

実際に移植できるものと、静かに移植できないもの​

仕様全体は可搬性のために設計されたが、実世界のスキルには 3 つの失敗モードがある。

使うもの可搬？理由
name、description、Markdown 本体✅ はいコア仕様。すべての適合エージェントが同一に読む。
本体から参照される scripts/、references/、assets/✅ はいディレクトリ配置は仕様の一部；本体が指示すればエージェントは読む。
license、metadata✅ はい（無視安全）任意フィールド — 非対応エージェントはエラーなくスキップする。
allowed-tools frontmatter⚠️ 部分的仕様上は実験的とマークされ；エージェント間で構文が標準化されていない。Claude Code は 1 つの形式を、Codex CLI は別の形式を尊重し、他のほとんどは完全に無視する。
Claude Code の when_to_use リスト❌ Claude 専用Codex、Gemini CLI、他全員は静かに無視する。
Claude Code の context: fork サブエージェントフラグ❌ Claude 専用ポータブルでないサブエージェント実行セマンティクス — 他のどこでもモデル挙動が異なる。
agents/openai.yaml 拡張❌ Codex 専用設計上明示的にベンダースコープ。他のエージェントが無視するから こそ 可搬。

教訓は率直だ：name + description + Markdown 本体 + 3 つの任意サブディレクトリに絞れば、スキルはどこでも動く。コア 2 つを超えてどんな frontmatter フィールドに手を伸ばしても、1 つのエージェント向けに作っていることになる。 それは正当な選択だ — 真に必要なスキルもある — が、テンプレートをコピペしたからではなく、意図的にやれ。

起動が実際にどう動くか（エージェント別）​

仕様は ファイル を標準化するが、判断 は標準化しない。各エージェントは、起動時に読んだ description に対して独自の起動ロジックを走らせる：

  • Claude Code はモデルの現在ターン読み取りを description と（存在すれば）Claude 固有の when_to_use リストと照合する；起動はモデルの判断で、キーワードルールではない。
  • Codex CLI は同じ description 駆動起動を使い、agents/openai.yaml で任意にオーバーライド可能。
  • Gemini CLI も同様に起動時に description をロードし、Gemini に選ばせる；挙動は Gemini 自身のツール選択ヒューリスティクスに従う。
  • Cursor、Junie、Kiro、Goose すべてが description 駆動起動を実装し、重み付けに軽い差異がある。

実践的帰結：あるエージェントで発火せず別で動くスキルは、ほぼ確実に description の問題であり、本体の問題ではない。description を ユーザーのリクエスト形 を語るように書き直し、スキルの内部 を語らないようにすれば、すべてのエージェントで一斉に発火率が上がる。

コピペできる可搬 SKILL.md​

以下は最小の、実際に可搬なコードレビュースキルだ。~/.agents/skills/code-reviewer/SKILL.md に置くだけで、Claude Code、Codex CLI、ChatGPT、Gemini CLI で無改変で動く。

code-reviewer/SKILL.md

---
name: code-reviewer
description: Reviews a diff or pull request for logic bugs, security issues, missing tests, and violations of project conventions. Use whenever the user asks for a review, code review, PR review, or "look at this diff / patch / change".
license: MIT
---

# Code Reviewer

You review code changes with the discipline of a staff engineer who cares
about the codebase surviving contact with reality. You are opinionated but
short. You never restate what the diff does — the user can read it.

## What to look at

1. **Logic bugs** — off-by-one, wrong operator, swapped arguments, unhandled
 error path, race, silent catch.
2. **Missing tests** — any changed behavior without a test is a finding.
3. **Security** — injection, secrets, missing auth checks, unsafe deserialization,
 unbounded input.
4. **Project conventions** — if a CLAUDE.md, AGENTS.md, .cursorrules, or README
 exists in the repo root, load it and enforce what it says.
5. **Complexity that will hurt future readers** — call it out, propose the
 simpler shape.

## What NOT to do

- Do not comment on formatting the linter will catch.
- Do not praise. No "great work" / "nice refactor".
- Do not summarize the diff. Assume the reader read it.

## Output format

For each finding, one line:

`path:line — <severity>: <problem>. <concrete fix>.`

Severities: 🔴 blocker, 🟠 important, 🟡 nit.

End with a one-line verdict: "ship", "ship with fixes", or "rework".

このスキルは 1 行残らず、すべての適合エージェントで動く。frontmatter にベンダースコープなものは何もない。本体はどのエージェントも解析するプレーンな Markdown 見出しを使う。

非 可搬な変種と比較しよう — さりげなく Claude 専用だ：

Claude 専用の変種（可搬性が欲しいなら使うな）

---
name: code-reviewer
description: Reviews a diff or pull request.
when_to_use:
- user asks for a review
- user pastes a diff
context: fork
allowed-tools: [Bash, Read, Grep]
---

3 つのものが同時に可搬性を壊す：when_to_use（Claude Code 専用）、context: fork（Claude Code のサブエージェントセマンティクス）、allowed-tools（実験的、一貫して尊重されない）。Codex は description を「Reviews a diff or pull request」として読む — これは曖昧すぎて滅多に起動しない — そして残りを無視する。

セキュリティ像（自分に正直になれ）​

どのマーケットプレイスからスキルをインストールするときも不快な真実：スキルは、あなたの環境であなたの権限で動く非常に高機能なエージェントへの任意の指示だ。 標準はコード署名、サンドボックス、必須レビュー、ランタイム権限モデルを何も規定していない。設計上、テキストファイル仕様であり、セキュリティ仕様ではない。

具体的な数字（大規模な公開スキルカタログの独立解析より、引用前にソースで確認）：

  • 公開共有スキルの約 3 分の 1 に、少なくとも 1 つのセキュリティ関連の欠陥がある — 過度に広いシェル指示、ハードコードされたシークレット、信頼できない URL 呼び出し、curl | sh 型のブートストラップ手順。
  • 少数だがゼロではないスキルが、露骨に悪意あるものとしてフラグ付けされている — 流出試行、認証情報収集、破壊的操作。
  • スキルはエージェントが継承するものを継承する。エージェントが ~/.ssh/ を読めるなら、インストールしたスキルもそうだ。

実際に効く実践的防御：

Guided walkthrough1 of 4
  1. Markdown だ。1 分でできる。description に「散文を整形する」とあり、本体に見覚えのない URL への `curl` があれば、そこで止まれ。

スキルがどう侵害され、何を確認すべきかの深掘りは、エージェントスキルの精査 と 攻撃を受けるコーディングエージェント を参照。

スキルを書くべきときと、単にプロンプトするべきとき​

スキルカタログの新任メンテナーは過剰生産しがちだ。有用なルール：

  • プロンプト は 1 回きりのタスクや、1 プロジェクトでしか使わない形に。スキルには起動コストがある — たとえ小さくても — し、description 予算を散らかす。
  • スキルを書け は、同じ指示が多くのチャットやプロジェクトに適用される場合（コードレビュー、コミットメッセージ書き、changelog 生成、請求書抽出）かつ description が明確に書ける場合。クリスプな description が書けなければ、スキルは信頼できる形で発火しない。
  • サブエージェントに手を伸ばせ は、タスクが独自のツールセット、独自のモデル選択、あるいは真の並列性を必要とする場合。スキルは メイン モデルに指示する；サブエージェントは別プロセスで動く。サブエージェント を参照。

関連読み物​

理解度チェック​

Check yourself

0/4
  1. 100 個のスキルをインストールした。起動時にその description はエージェントの context をおおよそ何トークン消費するか？
  2. Claude Code では動くのに、Codex CLI と Gemini CLI ではスキルを静かに壊す frontmatter フィールドはどれか？
  3. 書いたスキルが Claude Code では確実に発火するのに、Codex CLI では滅多に発火しない。最初に直すべき最も効果の高いものは？
  4. ロックファイルと監査ツールを持つ npm パッケージなどと比べて、Agent Skills のセキュリティ姿勢が根本的に弱いのはなぜか？

ソース & 追加読み物​