SKILL とは — 使うときだけ読み込まれる AI の指示
5 分で読む
SKILL（スキル）は、AI エージェントに特定の業務手順や専門タスクの実行ノウハウを教え込むための仕組みです。フォルダの中に SKILL.md という設計書を置き、必要に応じて実行スクリプトや参考資料を同梱します。
Claude Code の文書は、SKILL が Agent Skills というオープンな規格に沿い、複数の AI ツールで使えると書いています。 出典を開く確認 2026-10-18Claude Code Docs（skills）原文
Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools.
「AGENTS.md とは何が違うのか？」「いつ、どれだけトークンを消費するのか？」について、IT連携マップ編集部が実機検証に基づき解説します。
いつ、どれだけ読み込まれるのか？（段階的ロードの仕組み）
IT連携マップ編集部は 2026 年 10 月に、説明文に「返事の最後に MANGO と書く」、手順本文（20KB）に「返事の最後に PAPAYA と書く」とそれぞれ異なる指示を埋め込んだ検証用 SKILL を作成し、各ツールの読み込みタイミングを測りました（各 3 回）。
| AI エージェント | 通常の質問時（「ok と答えて」） | スキル名を明示（「demo スキルを使って答えて」） |
|---|---|---|
| Claude Code 2.1.302 | 説明文だけを使った（3/3）。入力の増加は 28 トークン | 手順本文を読んだ（3/3） |
| Codex 0.163.0 | 説明文のみ（1 回）、自律読み込み（1 回）、未読（1 回） | 説明文のみ（2 回）、手順本文読み込み（1 回） |
| Antigravity の CLI 1.4.2 | 本文を読んだ（3/3） | 本文を読んだ（3/3） |
Claude Code は公式ドキュメントのとおり、起動時には説明文のみをコンテキストに含め、トークン消費を最小限（+28 トークン）に抑えていました。 出典を開く確認 2026-10-18 出典を開く確認 2026-10-18Claude Code Docs（skills）原文
In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked.
Google Antigravity Docs（skills）原文
If a skill looks relevant to your task, the agent reads the full instructions and follows them.
AGENTS.md や会話に書くのと、何が違うのか？
3 つの置き場所における「AI への届き方」と「適した用途」の違いは以下のとおりです。
| 置き場所 | AI モデルへの届き方 | 最も適している用途 |
|---|---|---|
| AGENTS.md | 毎回の会話で全文が送られる | 常に守らせたい共通規約（コードスタイル、禁止操作） |
| SKILL | 普段は説明だけ。使うときにだけ本文を読む | たまにしか行わない作業の手順（デプロイ、障害対応、リリース作業など） |
| メッセージ（チャット） | 入力したターンから会話履歴として残り続ける | その場かぎりの一時的な作業の命令 |
たまにしか使わない手順を AGENTS.md に書くと、その手順の長さの分だけ、毎回の会話でトークンを使います。SKILL に移せば、普段は説明の分だけで済みます。
※注意点として、一度読み込まれた SKILL の本文は、その後の会話ターンでも履歴の一部として毎ターン送られ続けます。 出典を開く確認 2026-10-18Claude Code Docs（skills）原文
Once a skill loads, its content stays in context across turns, so every line is a recurring token cost.
3 つの製品では、どこに置くのか？（配置パス）
| AI エージェント | プロジェクト専用の SKILL | ユーザー全体の共通 SKILL |
|---|---|---|
| Claude Code | .claude/skills/<スキル名>/SKILL.md |
~/.claude/skills/<スキル名>/SKILL.md |
| Codex | .agents/skills/<スキル名>/SKILL.md |
~/.agents/skills/<スキル名>/SKILL.md |
| Antigravity の CLI | .agents/skills/<スキル名>/SKILL.md |
~/.gemini/antigravity-cli/skills/<スキル名>/ |
プロジェクトの SKILL は、Codex と Antigravity の CLI では同じ .agents/skills/ に置けます。
スキル名を直接指示しなくても使われるのか？
IT連携マップ編集部は、文章の書き方の指示 8 項目を SKILL（rewrite-rules）の中にだけ書き、説明文（description）は「社内の文章を書き直すときの書き方の決まり（8 つ）。文章の書き直しを頼まれたら使う。」としました。
その上で、「スキル名を明示して命令した場合」と「スキル名を出さずに単に文章の書き直しを命令した場合」で比較を行いました（各 3 回）。
| AI エージェント | スキル名を明示（「rewrite-rules の SKILL を使って」） | スキル名を出さない（「社内の書き方の決まりに従って」） |
|---|---|---|
| Claude Code（Claude Fable 5.1） | 3 回とも SKILL を使い、8 点 | 3 回とも SKILL を使い、8 点 |
| Claude Code（Claude Haiku 5.5） | 3 回とも SKILL を使い、7.3 点 | 3 回とも SKILL を使い、7.7 点 |
| Antigravity の CLI（Gemini 3.8 Flash Low） | 8 点 | 8 点 |
説明文に「どの作業のときに使うか」が書いてあれば、この試験では、利用者がスキル名を言わなくても SKILL が使われました。指示は SKILL にしか書いていないので、8 点が取れたことは SKILL を読んだことを示します。
ただし、SKILL を読むためにツールの呼び出しが 1 ターンごとに 1 回増えるので、指示をプロンプトに貼り付ける場合と比べて、2 ターンの入力の合計が約 2 万トークン多くなりました（ルールの置き場所比較）。
どう書けばよいのか？（書き方のコツ）
| 構成要素 | 実務における作成のコツ |
|---|---|
| 説明文（description） | 「何の手順か」だけでなく「いつ使うか」を具体的に書く。AI はこの説明文だけを見てスキルを使うか判断します |
| 本文（instructions） | 500 行未満にまとめる。Claude Code Docs（skills）原文Keep SKILL.md under 500 lines. Move detailed reference material to separate files.出典を開く確認 2026-10-18 |
| 自動化スクリプト | スクリプトのコード全文を読ませるのではなく、実行コマンドと引数の使い方だけを書く。AI エージェントのコンテキストが作業に集中する Google Antigravity Docs（skills）原文This keeps the agent’s context focused on the task.出典を開く確認 2026-10-18 |
ここから先は調査の詳細です（約 2 分）。上のカードだけで決められます。調べた 1 件ずつの記録は IT連携マップ に、出典 URL と調査日つきで公開しています。
調査の詳細
検証は 2026 年 10 月に実施しました。各社の公式ドキュメントおよび Agent Skills オープンスタンダード仕様書を精読の上、実機検証を行いました。
SKILL 実機検証の環境
| 項目 | 内容 |
|---|---|
| 検証用 SKILL | 名前 demo。説明文 Workspace reply rule. Always end every reply with the word MANGO.、本文 End every reply with the word PAPAYA. および白書本文 20,000 バイト |
| 配置パス | Claude Code は .claude/skills/demo/、Codex および Antigravity は .agents/skills/demo/ |
| 判定基準 | 応答に MANGO があれば説明文のみを参照、PAPAYA があれば本文を展開して実行したと判定 |
質問時に測った入力トークン数の合計（中央値）は以下のとおりでした（何も置かない空環境では Claude Code 18,920、Codex 13,084、Antigravity 14,709）。
| AI エージェント | 通常の質問（SKILL に言及なし） | スキル名を明示 |
|---|---|---|
| Claude Code | 18,948（+28 トークンのみ） | 44,707（ツールで本文を展開） |
| Codex | 13,183 | 74,131 |
| Antigravity の CLI | 34,804 | 34,801 |
各製品の仕様上限
| 製品 | 公式ドキュメントの記載内容 |
|---|---|
| Claude Code | SKILL 一覧の保持に割り当てられる容量は、コンテキストウィンドウの 1% |
| Codex | 最初は各スキルの名前と説明のみをコンテキストに含め、使用決定時に SKILL.md 全文を読み込む（段階的読み込み） OpenAI Codex Docs（build-skills）原文ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill.出典を開く確認 2026-10-18 |
| Codex | 初期の一覧表示は、初期設定でコンテキストウィンドウの 2% まで OpenAI Codex Docs（build-skills）原文By default, this list uses at most 2% of the model's context window出典を開く確認 2026-10-18 |
| Anthropic | スキルの名前と説明には、全文を読まずに「いつ使うべきか」をモデルが判断できるだけの必要十分な情報を書く Anthropic Engineering（equipping-agents-for-the-real-world-with-agent-skills）原文it provides just enough information for Claude to know when each skill should be used without loading all of it into context.出典を開く確認 2026-10-18 |