Agent Skills は、AI エージェントに手順をもたせるための、軽量で公開された形式です。中身は「SKILL.md という1枚の Markdown が入ったフォルダ」。それだけです。
もとは Anthropic が作り、公開標準として出されました。いまは Claude Code のほか、Cursor、GitHub Copilot、Gemini CLI、OpenCode など多くのエージェントが読み込めます。1つ書けば、対応しているエージェントで使い回せるのが、この形式のいちばんの意味です。
公式ドキュメントを読む(外部サイト) 標準仕様サイト(外部サイト)フォルダ1つが、1つの Skill
最小の構成はこうです。
my-skill/
├── SKILL.md 必須。メタデータと手順
├── scripts/ 任意。実行するコード
├── references/ 任意。参照用の文書
└── assets/ 任意。テンプレートなどSKILL.md は2つの部分でできています。--- で囲んだ YAML のフロントマターと、その下の Markdown 本文です。
---
name: my-skill
description: What this skill does
---
ここに手順を書く先頭の --- がファイルの1行目にないと、全体がただの本文として扱われます。 空行やコメントを上に置かないでください。
フロントマターの項目
Claude Code のドキュメントが挙げている主なものです。
| 項目 | 必須 | 役割 |
|---|---|---|
name | いいえ | / メニューに出る名前。省略するとフォルダ名 |
description | 推奨 | 何をするもので、いつ使うか。エージェントはこれを読んで使うかどうかを決める |
disable-model-invocation | いいえ | true にすると、エージェントが自動で呼ばなくなる |
allowed-tools | いいえ | そのターンの間、確認なしで使ってよいツールを先に許可する |
このほかに when_to_use、argument-hint、arguments、user-invocable、disallowed-tools、model、effort、context、paths、shell といった項目があります。
どこに置くと読まれるか
Claude Code は決まった場所を見にいきます。同じ名前があるときの強さは enterprise > personal > project です。
| 置き場所 | パス | 効く範囲 |
|---|---|---|
| 個人 | ~/.claude/skills/<skill-name>/SKILL.md | その PC の全プロジェクト |
| プロジェクト | .claude/skills/<skill-name>/SKILL.md | そのリポジトリでの作業 |
| 下位ディレクトリ | <subdir>/.claude/skills/<skill-name>/SKILL.md | そのディレクトリ以下での作業 |
| 企業配布 | 管理された設定ディレクトリの .claude/skills/<skill-name>/SKILL.md | 配布された全利用者 |
プラグインのものは <plugin>/skills/<skill-name>/SKILL.md、claude.ai から同期したものは ~/.claude/skills/synced/ に置かれます。
全部を読み込むわけではない
ここが Skill の設計のかなめです。**段階的な開示(progressive disclosure)**といい、3段階に分かれています。
- 発見 — 起動時には、各 Skill の名前と説明だけが読み込まれます。「何があるか」を知るだけの、ごく小さな情報です
- 起動 — 依頼が説明と噛み合ったときに、はじめて
SKILL.mdの全文が文脈へ入ります - 実行 — 手順にしたがい、必要なら同梱のコードを動かしたり、参照ファイルを読んだりします
Claude Code のドキュメントでは、description と when_to_use を合わせて最大 1,536 文字が毎ターン読み込まれる、と書かれています。全文が入るのは呼ばれたときだけ。一度呼ばれると、そのセッションの間は文脈に残ります。
つまり、たくさん持っていても普段の負担は小さい。そのかわり description の書き方が死活的です。ここが曖昧だと、必要な場面で呼ばれません。
呼び出し方は3通り
- 自分で
/skill-nameとメッセージの先頭に打つ - 依頼の内容が
descriptionと合ったとき、エージェントが自動で選ぶ - Agent SDK や Remote Control から明示的に実行する
自動で呼ばれたくないものは disable-model-invocation: true を立てておきます。
向いている用途
公開標準のサイトでは、次の3つが挙げられています。
- 専門知識 — 法務レビューの手順、データ分析の流れ、資料の体裁。再利用できる形で閉じ込める
- 繰り返す作業 — 複数の工程を、毎回同じ順で、あとから追える形にする
- 道具をまたいだ再利用 — 一度書けば、対応するエージェントならどこでも使える
逆に、外部のサービスへ接続したり、その場で計算した値を返したりするのは Skill の仕事ではありません。そこは MCP の領分です。違いは SkillとMCPの違い にまとめました。
この記事について
Claude Code の公式ドキュメントと、標準仕様サイトの記述を読んで書いています。手元で全項目を動かして確かめた記録ではありません。 仕様は更新されるため、導入前には出典のページをご確認ください。
SOURCES
この記事を書くときに参照した資料と、内容を確認した日です。
- Agent Skills — Claude Code 公式ドキュメント(外部サイト)確認 2026.10.12
- Agent Skills — 標準仕様サイト(外部サイト)確認 2026.10.12
