クイックサマリー: SKILL.md（Agent Skills 標準）は、AIエージェントに専門知識や作業手順を教えるためのオープンなファイル形式です。Claude Code・OpenAI Codex・GitHub Copilot・Cursor・Gemini CLI・Goose・OpenCode など約40のプロダクトが対応しており、1つ書けば複数のエージェントで同じスキルが動きます。本記事では仕様の要点・最小構成・配置場所・書き方のコツを解説します。
SKILL.mdとは — 「1回書けばどのエージェントでも動く」共通標準
AIコーディングエージェントを日常的に使っていると、「同じ指示を毎セッション繰り返している」「Claude Code 用に作った手順書が Codex では使えない」という課題に直面します。SKILL.md はこの課題を解決するために生まれた形式で、エージェントに実行させたいタスクの手順・判断基準・参照資料を、バージョン管理可能なフォルダとしてパッケージ化します。
公式サイト（agentskills.io）によると、Agent Skills はもともと Anthropic が Claude Code 向けに開発した形式で、その後オープン標準として公開され、エコシステム全体からのコントリビューションを受け付けています。2026年6月時点で約40のプロダクトが対応しており、事実上の業界標準になりつつあると考えられます。ライセンスはオープンな仕様として公開されており、スキル自体は自分のリポジトリで自由に管理できます。
- SKILL.md の最小構成と必須メタデータがわかる
- Claude Code / Codex CLI / Gemini CLI / Antigravity CLI での配置場所がわかる
- CLAUDE.md・AGENTS.md・MCP との使い分けがわかる
- 実開発フローに組み込む具体例がわかる
何ができるか — 対応エージェントと仕組み
対応プロダクトには Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Goose、OpenCode などが含まれます。スキルの実体は「SKILL.md を含むフォルダ」で、公式ドキュメントでは次の構成が示されています。
my-skill/
├── SKILL.md # 必須: メタデータ + 手順
├── scripts/ # 任意: 実行可能コード
├── references/ # 任意: 参照ドキュメント
└── assets/ # 任意: テンプレート等重要なのは「プログレッシブ・ディスクロージャー（段階的読み込み）」という仕組みです。公式ドキュメントによると、エージェントは起動時に各スキルの name と description だけを読み込み（Discovery）、タスクがスキルの説明に合致したときに初めて SKILL.md 全文をコンテキストに読み込みます（Activation）。その後、必要に応じて同梱スクリプトの実行や参照ファイルの読み込みを行います（Execution）。この設計により、数十個のスキルを手元に置いてもコンテキスト消費はごくわずかで済みます。CLAUDE.md のような「常時全文ロード」型との最大の違いがここにあります。
インストール・配置手順（CLI別）
SKILL.md は「インストール」というより「所定のフォルダに置く」だけで有効化されます。CLI ごとの配置場所は次のとおりです。
Claude Code の場合: 個人用は ~/.claude/skills/、プロジェクト共有用はリポジトリ内の .claude/skills/ に、スキル名のフォルダを作って配置します。
mkdir -p ~/.claude/skills/pdf-report
cd ~/.claude/skills/pdf-report
touch SKILL.md配置後、Claude Code を起動して該当タスクを依頼するか、/skills 相当の一覧表示でスキルが認識されているかを確認します。CLAUDE.md に「PDF出力はスキルに従う」のような一文を足すと発火率が安定します。
Antigravity CLI（agy）の場合: ワークスペース単位では <プロジェクトルート>/.agents/skills/、グローバルには ~/.gemini/antigravity-cli/skills/ に同じフォルダ構成で配置します。ファイル形式は共通なので、Claude Code 用に書いたフォルダをそのままコピーするだけで動作します。
Codex CLI / Gemini CLI の場合: それぞれのドキュメントで指定されたスキルディレクトリに同一フォルダを配置します。フォーマット自体は共通のため、書き直しは不要です。複数 CLI を併用するチームでは、リポジトリに skills/ フォルダを1つ置き、各 CLI の設定ディレクトリへシンボリックリンクを張る運用が管理しやすいと考えられます。
SKILL.mdの書き方 — 最小構成と設定例
SKILL.md の先頭には YAML フロントマターでメタデータを書きます。必須は name と description の2つです。
---
name: pdf-report
description: 月次レポートをPDF化するスキル。「PDFにして」
「レポート出力」等のリクエストで使用する。
---
# PDFレポート生成手順
1. `reports/` 配下の対象Markdownを特定する
2. `scripts/build_pdf.py` を実行する
3. 出力PDFのページ数と目次を確認して報告する書き方のコツは次の3点です。第一に、description が発火条件のすべてだという点です。エージェントは description だけを見てスキルを使うか判断するため、「何ができるか」に加えて「どんな依頼のときに使うか」まで書きます。第二に、本文は手順書として具体的に書き、判断基準（成功条件・失敗時の対応）を含めます。第三に、長い参照資料は SKILL.md に直接書かず references/ に分離し、「必要なら references/spec.md を読む」と誘導します。これにより段階的読み込みの利点を最大化できます。
実開発フローでの活用例
実際の開発タスクへの組み込み例をいくつか挙げます。
例1: リリース手順の標準化（バックエンド開発者）。「バージョン更新 → CHANGELOG 追記 → タグ作成 → デプロイ確認」という定型フローを release スキルにしておけば、Claude Code でも Codex CLI でも「リリースして」の一言で同じ手順が再現されます。担当者やツールが変わっても手順が揺れません。
例2: 社内レビュー基準の配布（テックリード・QA）。コードレビューの観点（セキュリティ・命名規約・テスト有無）をスキル化してリポジトリの .claude/skills/ にコミットすれば、チーム全員のエージェントが同じ基準でレビューします。Claude Code のサブエージェントと組み合わせて、観点別に並列レビューさせる構成も可能です。
例3: データ分析パイプラインの再現（データアナリスト）。「CSVの前処理 → 集計スクリプト実行 → グラフ生成」の手順とスクリプトを1フォルダにまとめておけば、毎月の定例分析が「先月と同じ分析をして」で完了します。公式サイトでも、データ分析パイプラインや法務レビュープロセス、プレゼン整形などがユースケースとして挙げられています。
CLAUDE.md・AGENTS.md・MCPとの比較
「どのファイルに何を書くべきか」は頻出の疑問です。役割の違いを表で整理します。
| ツール名 | 対応CLI | ライセンス | 最終更新 | 特徴 |
|---|---|---|---|---|
| SKILL.md（Agent Skills） | Claude Code / Codex / Copilot / Cursor / Gemini CLI 等 約40製品 | オープン標準 | 活発（2026年） | タスク単位の手順書。必要時のみ全文ロードされ、スクリプト同梱可 |
| CLAUDE.md | Claude Code 専用 | —（設定ファイル） | — | プロジェクト全体の常時コンテキスト。毎セッション全文ロード |
| AGENTS.md | Codex / Cursor 等 複数エージェント | オープン標準 | 活発（2026年） | CLAUDE.md のクロスツール版。プロジェクト説明が主目的 |
| MCP サーバー | Claude Code / Cursor 等 MCP対応クライアント | オープン標準 | 活発（2026年） | 外部システムへの「接続」を提供。知識・手順の提供はスキルの役割 |
使い分けの目安は「常に必要な前提 → CLAUDE.md / AGENTS.md」「特定タスクの手順 → SKILL.md」「外部ツール・データへの接続 → MCP」です。三者は排他ではなく、レイヤーとして併用するのが実践的です。
注意点・制約・セキュリティ
導入前に押さえておきたい点が3つあります。
第三者スキルの監査: スキルは scripts/ に実行可能コードを同梱できるため、コミュニティ配布のスキルをインストールする行為は「他人のコードを自分の環境で実行させる」ことと同義です。導入前に SKILL.md 本文と同梱スクリプトを必ず読み、外部への通信やファイル削除を行うコードがないか確認してください。
外部通信はスキル自体には無い: SKILL.md はただのテキストファイルで、それ自体がデータを外部送信することはありません。実際の実行はホスト側 CLI の権限モデル（Claude Code なら permissions 設定）に従います。
対応度の差: 約40製品が「対応」といっても、段階的読み込みの実装度やフロントマターの解釈には差があります。複数 CLI で共用する場合は、必須2項目（name / description）と標準構成に寄せた保守的な書き方が安全と考えられます。
まとめ
- SKILL.md は「フォルダ + メタデータ + 手順書」だけのシンプルなオープン標準で、約40のエージェント製品に対応しています
- 段階的読み込みにより、多数のスキルを置いてもコンテキスト消費が小さく済みます
- description の書き込みが発火精度を決めるため、「何ができるか + いつ使うか」を必ず両方書きます
まずは毎回繰り返している指示を1つ選び、SKILL.md にしてみることをおすすめします。仕様の詳細は Agent Skills 公式ドキュメントを参照してください。Claude Code ではスキル機能が標準搭載されており、追加インストールなしで今日から試せます。
コメント