2026年10月18日 / 最終更新日 : 2026年10月18日 fujifuji コラム

Agent Skillsとは？SKILL.mdの書き方と使えるツール（Claude Code・Codex・GitHub Copilot）

Agent Skills（エージェントスキル）とは、AIエージェントに仕事の手順や専門知識を渡すための共通の形式です。SKILL.mdを入れたフォルダを1つ置くだけで、Claude Code・Codex・GitHub Copilotなど対応するAIが、必要なときにその手順を読み込んで使います。

この記事では、Agent Skillsの仕組み、SKILL.mdの書き方と仕様の決まり、ツールごとの置き場所の違いを、公式の仕様と各社のドキュメント（いずれも2026年10月18日確認）をもとに整理します。仕様に沿っているかを確かめる公式の検証ツールも実際に動かしました。claude.aiに最初から入っている文書作成用のスキルについては「Claudeのスキルとは何か」で扱っています。

Agent Skillsとは：手順書をフォルダにまとめる共通規格

Agent Skillsの公式サイトは、スキルを「SKILL.mdファイルを含むフォルダ」と説明しています。SKILL.mdには名前と説明（メタデータ）と、作業のやり方の指示を書きます。フォルダにはスクリプトや参考資料、テンプレートも同梱できます。

my-skill/
├── SKILL.md      # 必須：メタデータと指示
├── scripts/      # 任意：実行できるコード
├── references/   # 任意：参考資料
└── assets/       # 任意：テンプレートなど

この形式はAnthropicが開発し、2025年10月16日に発表、同年12月18日にオープン標準として公開されました。いまでは他社のAIエージェントも同じ形式のスキルを読み込めます。

「毎回同じ指示を書くのが面倒」「チームのやり方をAIに覚えさせたい」という悩みに対し、手順をファイルにして使い回せるようにするのがスキルの役割です。

Agent Skillsの仕組み：必要なときだけ読み込む

スキルの一番の特徴は、中身を最初から全部読み込まないことです。公式サイトでは「段階的な開示（progressive disclosure）」と呼び、次の3段階で説明しています。

段階	AIが読み込むもの
1. 発見	起動時に、各スキルのnameとdescriptionだけ
2. 有効化	依頼がdescriptionに合ったとき、そのスキルのSKILL.md全体
3. 実行	指示に従い、必要になったら同梱のスクリプトや資料

このため、スキルをたくさん入れても、普段消費するのは名前と説明の分だけで済みます。逆に言えば、AIが「いまこのスキルを使うべきか」を判断する材料はdescriptionだけです。descriptionの書き方がスキルの効き目を左右します。

SKILL.mdの書き方と仕様の決まり

SKILL.mdは、先頭の---で囲んだフロントマター（YAML）と、その下の本文（Markdown）でできています。仕様で決まっている項目は次のとおりです。

項目	必須	決まり
`name`	必須	64文字まで。小文字の英数字とハイフンのみ。先頭・末尾のハイフンと連続したハイフンは不可。フォルダ名と同じにする
`description`	必須	1024文字まで。何をするかと、いつ使うかの両方を書く
`license`	任意	ライセンス名か、同梱したライセンスファイル名
`compatibility`	任意	500文字まで。必要な環境（対象製品、必要なコマンド、ネット接続など）
`metadata`	任意	作者やバージョンなど、自由なキーと値
`allowed-tools`	任意	事前に許可するツールをスペース区切りで（実験的。対応は製品により異なる）

本文の書き方に決まりはありません。仕様では、手順、入力と出力の例、よくある例外を書くことを勧めています。スキルが有効になると本文は丸ごと読み込まれるので、長い資料はreferences/に分けておくと無駄がありません。

例：Pythonのコードレビュー用スキル

チームの規約に沿ってレビューさせるスキルを作ってみます。フォルダ名とnameをどちらもcode-reviewにします。

---
name: code-review
description: Pythonのコードをチーム規約に沿ってレビューする。プルリクエストのレビューや「レビューして」と頼まれたときに使う。
---

# コードレビュー

1. `python scripts/count_todo.py <ファイル>` を実行し、残っているTODOの数を確認する
2. 関数名・変数名がsnake_caseかを確認する
3. 例外を握りつぶしている箇所（`except: pass`）を指摘する
4. 指摘は「重大」「推奨」「好み」の3段階に分けて箇条書きで返す

手順1で呼んでいる同梱スクリプトscripts/count_todo.pyです。

import sys
from pathlib import Path

text = Path(sys.argv[1]).read_text(encoding="utf-8")
count = sum(1 for line in text.splitlines() if "TODO" in line)
print(f"TODO: {count}件")

TODOを2か所含むファイルに対して実行した結果です（Python 3.12）。

TODO: 2件

数を数える、形式を確かめるといった決まった処理はスクリプトにし、判断が必要な部分を文章の指示にする、という分け方がスキルの作り方の基本です。

descriptionは「何を」と「いつ」を書く

仕様には良い例と悪い例が載っています。「Helps with PDFs.（PDFを手伝う）」は悪い例で、良い例は「PDFから文章と表を取り出し、フォームに記入し、複数のPDFを結合する。PDFを扱うときや、ユーザーがPDF・フォーム・文書の抽出に触れたときに使う」のように、作業内容と使う場面を具体的に書いています。上のレビュー用スキルでも「プルリクエストのレビューや『レビューして』と頼まれたときに使う」と場面を入れています。

公式の検証ツールで仕様に合っているか確かめる

仕様のページでは、参照実装のskills-refで検証する方法が紹介されています。PyPIのskills-ref（0.1.1、リポジトリはanthropics/agentskills）をインストールすると、コマンド名はagentskillsでした（仕様のページの例はskills-ref validate）。

pip install skills-ref
agentskills validate ./code-review

Valid skill: code-review

わざと仕様に反する名前PDF--Toolのスキルを検証すると、次のように理由が表示されます。

Validation failed for PDF--Tool:
  - Skill name 'PDF--Tool' must be lowercase
  - Skill name cannot contain consecutive hyphens

agentskills to-promptを使うと、AIが「発見」の段階で受け取る一覧も確認できます。本文は含まれず、名前・説明・場所だけが渡されることが分かります。

<available_skills>
<skill>
<name>
code-review
</name>
<description>
Pythonのコードをチーム規約に沿ってレビューする。プルリクエストのレビューや「レビューして」と頼まれたときに使う。
</description>
<location>
/（作業フォルダ）/code-review/SKILL.md
</location>
</skill>
</available_skills>

Agent Skillsが使えるツールと置き場所

agentskills.ioの対応製品の一覧には40を超える製品が載っており、Claude Code、Claude、ChatGPTとCodex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiroなどが含まれます。形式は共通ですが、スキルを置く場所は製品ごとに違います。

ツール	プロジェクト用の置き場所	個人用の置き場所	呼び出し方
Claude Code	`.claude/skills/<名前>/`	`~/.claude/skills/<名前>/`	自動、または`/名前`
Codex（CLI・IDE拡張）	`.agents/skills/`	`~/.agents/skills/`	自動、または`/skills`・`$`で指定
GitHub Copilot	`.github/skills`・`.claude/skills`・`.agents/skills`	`~/.copilot/skills`・`~/.agents/skills`	関連する作業のとき自動
claude.ai（アプリ）	—	設定画面からzipでアップロード	自動

出典：Claude Code、ChatGPT・Codex、GitHub Copilot、Claude Platformの各公式ドキュメント（2026年10月18日確認）。

Claude Code：Agent Skillsの標準に、人だけが呼べるようにする設定やサブエージェントでの実行など独自の項目を足しています。同じ名前のスキルが個人用とプロジェクト用の両方にあると、個人用（~/.claude/skills/）が優先されます
ChatGPT・Codex：ChatGPTのデスクトップアプリ、Codex CLI、IDE拡張でスキルを使えます。$skill-creatorで、説明からスキルを作らせることもできます
GitHub Copilot：Copilotのクラウドエージェント、コードレビュー、Copilot CLI、VS CodeとJetBrains IDEのエージェントモードで使えます。.claude/skillsも読むので、Claude Code用に作ったスキルをそのまま共有できます
claude.ai：自作スキルのアップロードは、コード実行を有効にしたPro・Max・Team・Enterpriseプランが対象です

Claude Code独自の設定項目（引数の受け取り、コマンド結果の埋め込み、確認の省略など）は「Claude Code コマンド一覧」と「Claude Code の各種 MDファイル完全活用ガイド」で扱っています。

スキル・CLAUDE.md・MCP・サブエージェントの使い分け

仕組み	読み込まれるとき	向いている中身
スキル	依頼が説明に合ったとき（または人が呼んだとき）	ときどき使う手順書、長い参考資料、決まった処理のスクリプト
CLAUDE.md（AGENTS.md）	毎回のセッションの最初	プロジェクトの構成や規約など、常に守ること
MCP	接続している間	GitHub・データベースなど外部サービスへの接続
サブエージェント	作業を任せたとき、別のコンテキストで	大量のファイルを読む調査など、切り離せる作業

迷ったら「毎回必要か、ときどき必要か」で分けます。毎回必要なことをスキルにすると、呼ばれるまでAIはそれを知りません。逆にたまにしか使わない長い手順をCLAUDE.mdに書くと、関係のない作業でも毎回読み込まれてコンテキストを使います。サブエージェントは「サブエージェント完全ガイド」、AIエージェント全体の仕組みは「AIエージェントとは？」で解説しています。

スキルを使うときの注意点

中身を読んでから入れる：スキルはスクリプトを含められます。Claude Platformのドキュメントは、信頼できる提供元のものだけを使い、同梱ファイルをすべて確認し、想定外の外部通信やファイル操作がないか見るよう勧めています
権限の設定を確認する：allowed-toolsで確認なしにコマンドを実行させる設定は、どこまで許すかを決めてから使います。Claude Codeでの権限の考え方は「Claude Codeのセキュリティ」にまとめています
実行環境の違い：同じスキルでも、Claude APIでは外部のネット接続がない隔離された環境で動き、Claude Codeでは手元のPCと同じ権限で動きます
1つのスキルに詰め込まない：目的ごとに分けたほうが、descriptionで正しく選ばれやすくなります

生成AIやAIエージェントを使った開発を実際の課題で身につけたい方は、テックジムのAI駆動開発コースで、ChatGPT・Claude・Claude Code・Codex・Cursor・Geminiなどを使ってアプリや業務ツールを作りながら学べます。

まとめ

Agent Skillsは、SKILL.mdを入れたフォルダでAIに手順を渡す共通規格で、2025年12月にオープン標準になった
普段は名前と説明だけが読み込まれ、依頼が合ったときに本文が読まれる
必須はnameとdescription。descriptionには「何を」と「いつ」を書く
検証ツール（skills-ref）で仕様に合っているか確かめられる
Claude Code・Codex・GitHub Copilotなどで使えるが、置き場所は製品ごとに違う

よくある質問

Q. Agent Skillsとは何ですか？

AIエージェントに作業の手順や専門知識を渡すための共通の形式です。SKILL.mdというファイル1つを入れたフォルダが1つのスキルで、必要に応じてスクリプトや参考資料も同じフォルダに入れられます。Anthropicが開発し、2025年12月18日にオープン標準として公開しました。

Q. Agent SkillsはClaude専用ですか？

いいえ。agentskills.ioの対応製品一覧にはClaude Code、ChatGPTとCodex、GitHub Copilot、VS Code、Cursor、Gemini CLIなどが並んでいます。ただし置き場所や追加の設定項目は製品ごとに違うので、それぞれの公式ドキュメントで確認してください。