AI Coding Agent（Google Antigravity, Claude Code, Cursorなど）の開発現場で急速に普及している「SKILL.md」をご存知でしょうか？
単なるプロンプト（指示文）を超えて、AIに専門的なワークフローや独自のコーディング規約、手順書を効率的に教え込むための標準フォーマット仕様です。
本記事では、SKILL.mdの概要から注目される理由、内部の仕組み（プログレッシブ・ディスクロージャー）、具体的な書き方や活用方法まで詳しく解説します！
SKILL.md（スキル・ファイル）とは
SKILL.mdとは、AIエージェントに対して特定の専門作業（例：リファクタリング、特定のフレームワーク構築、WordPress投稿、データベース移行など）の手順やナレッジを提供するMarkdown形式の指示ファイルです。
AIエージェントツール（Antigravity、Claude Code、Agentic Framework等）は、プロジェクト内やグローバル設定にあるSKILL.mdを動的に読み込むことで、開発者の個別の要件や手順に最適化された「専属エキスパート」として機能します。
SKILL.mdが注目される理由と従来のプロンプトとの違い
従来のチャットAI（ChatGPTやClaudeの通常対話）では、毎回長いシステムプロンプトを入力したり、コンテキスト（文脈）の上限を気にしながら指示を出したりする必要がありました。
これに対してSKILL.mdは、以下のような画期的な特長を備えています。
| 比較項目 | 従来のプロンプト | SKILL.md（エージェントスキル） |
|---|---|---|
| 読み込みタイミング | 常時（または会話の最初）に全体を入力 | 必要な時だけ動的にオンデマンド読み込み |
| トークン消費コスト | 常に大量のトークンを消費 | 普段は名前と概要のみ（極めて軽量） |
| チーム共有・管理 | メモ帳やChat履歴で個別に共有 | Gitリポジトリ（.agents/skills/）でコード管理 |
| 拡張機能・スクリプト | プロンプトテキストのみ | Python/Shellスクリプトや参照用データと連携可 |
SKILL.mdの基本構造とディレクトリ構成
SKILL.mdは、YAMLフロントマター（メタデータ）と、Markdown形式の指示文（本文）で構成されています。
YAMLフロントマター（属性情報）
ファイルの先頭に---で囲まれたYAML形式のヘッダーを記述します。
---
name: wordpress-article-publisher
description: WordPress用の記事作成・自動投稿スクリプトの実行手順とスタイル規約を提供するスキル
---- name: スキルの識別名（英数字やハイフンで定義）。
- description: スキルの目的と、どのような場面でこのスキルを呼び出すべきかの概要。AIエージェントはこの文章を元に「今どのスキルが必要か」を自律判断します。
指示本文（Markdownセクション）
YAMLフロントマター以降の本文には、AIが実行すべき手順やルール、コード規約、ツール使用時の注意事項などを詳細に記載します。
ディレクトリ構成例
1つのスキルは単一のファイルだけでなく、補助スクリプトやリソースファイルと一緒にフォルダとしてパッケージ化できます。
.agents/
skills/
wordpress-publisher/
SKILL.md # スキル定義本体
scripts/
publish_api.py # 補助用実行スクリプト
resources/
template.html # 記事テンプレートSKILL.mdを支える「プログレッシブ・ディスクロージャー」とは
SKILL.mdの最も重要な技術コンセプトが「Progressive Disclosure（段階的情報開示）」です。
プロジェクト内に100個のスキルが存在していた場合、そのすべてを最初からAIのコンテキスト（記憶領域）に読み込むと、あっという間に制限を超過し、精度も低下してしまいます。
プログレッシブ・ディスクロージャーの動作フロー：
- 初期化時：AIエージェントは、各スキルの
nameとdescription（YAML部）のみを軽くインデックス化します。 - タスク検知：ユーザーから「WordPress記事を公開して」と頼まれると、AIはdescriptionを参照して最適なスキルを検出します。
- 動的ロード：該当する
SKILL.mdの本文ファイルを読み込み、具体的な手順やルールに従って作業を正確に実行します。
SKILL.mdの配置場所と優先順位
AntigravityなどのAIエージェント環境では、SKILL.mdを以下の優先順位（Scope）で認識します。
- プロジェクト固有スキル（Workspace Scope）
プロジェクトルート配下の.agents/skills/スキルのフォルダ名/SKILL.md
チームでGit共有でき、プロジェクトごとのビルド手順やデプロイ規約に最適です。 - ユーザー共通スキル（Global Scope）
ユーザーのホームディレクトリ配下（~/.gemini/config/skills/スキルのフォルダ名/SKILL.md）
個人のPC全体で共通して使いたいユーティリティや記事執筆ルールなどに適用されます。 - 組み込みスキル（Built-in Scope）
AIエージェントシステム本体に標準で同梱されている基本スキル。
※同名のスキルが存在する場合、プロジェクト固有（Workspace）のスキルが優先されます。
実践！SKILL.mdの作成手順と具体的な書き方
実際に自分だけのカスタムSKILL.mdを作成してみましょう。
ステップ：フォルダとSKILL.mdの作成
プロジェクトルートに.agents/skills/my-first-skill/ディレクトリを作成し、その中にSKILL.mdを作成します。
ステップ：YAMLフロントマターの記述
AIが正確に用途を判断できるように、簡潔で具体的なdescriptionを書くことがコツです。
ステップ：エージェント向け指示プロンプトの作成
見出しや箇条書きを活用し、AIが迷わないクリアなステップを定義します。
具体例：WordPress記事作成用SKILL.md
---
name: wordpress-formatting-rules
description: WordPress向けブログ記事を作成する際のCSSクラス指定および見出しルール
---
# WordPress記事スタイル規約
## 見出しのスタイル規約
- 見出し（h1, h2, h3, h4）の先頭に数字や連番を絶対に付与しないでください。
## 補足コールアウトのデザイン
- 枠線はシンプルな薄いボーダー（border: 1px solid #e2e8f0）を使用してください。
## コードブロック
- コード例は必ず pre code タグで囲み、背景色 #1e293b を指定してください。SKILL.mdを導入するメリット
- チーム全体でのナレッジ共有：Gitにコミットするだけで、チーム全員のAIエージェントが同じ開発手順・コーディング規約を自動で遵守。
- コンテキストの大幅節約：数多くのナレッジがあっても、必要な時だけ呼び出すためコストパフォーマンスが高く動作も高速。
- 指示の再利用性と再現性：毎回同じプロンプトを入力する手間がなくなり、AIの出力品質が常に安定。
まとめ：SKILL.mdでAIアシスタントを真のチームメンバーへ
SKILL.mdは、AIエージェントを単なる「汎用回答AI」から「プロジェクト専用の高度なパートナー」へと進化させる強力な仕組みです。
日常的な定型作業、コードレビュー規約、記事の執筆ルールなどをSKILL.mdとして定義しておくことで、AIとのペアプログラミング・ペアライティングの生産性が飛躍的に向上します。
ぜひ皆様のプロジェクトでも.agents/skills/を作成し、自作のSKILL.mdを活用してみてください！
