Agent Skillsは、AIエージェントへ業務手順と専門知識を渡すためのディレクトリ形式です。Anthropicが2025年10月16日に公開し、同年12月18日にクロスプラットフォームの移植性を目的としたオープン標準へ切り出されました。2026年9月18日時点で46製品が対応を表明しています。ただし「どの製品でも同じスキルが動く」とは限らない。書き方しだいで1製品専用の資産に変わってしまう。この記事では共通仕様のフロントマター6フィールド、Progressive disclosureのトークン会計、Claude Codeでの配置先、移植性を壊す独自フィールドの境界を整理します。
まとめ：Agent Skills導入で先に決める配置先と移植性の線引き
最初に決めるのは配置先です。claude.ai・Claude API・Claude Codeの3サーフェスでスキルは同期せず、共有範囲も別物になります。claude.aiへ上げたスキルは各自が個別にアップロードする個人資産で、管理者による一元管理も組織配布もできません。チームで同じ手順を共有するなら、Claude Codeのプロジェクト配置かAPIワークスペースのどちらかを先に選んでから中身を書き始めてください。
移植性の線引きははっきりしています。46製品で動かしたいなら、フロントマターは共通仕様の6フィールドだけに絞ること。contextやmodelといったClaude Code独自フィールドは便利な反面、書いた瞬間にそのスキルは専用資産へ変わります。指示文は共通、実行制御は各製品の設定側という分離が現実解です。もう1点、スキル化しない業務も決めます。Agent Skillsはゼロデータ保持の対象外なので、保持ポリシーで縛られた業務手順は社内の手順書側へ残してください。
Agent Skillsの定義とSKILL.mdが必須とする2フィールドの制約値
実体はフォルダです。中にSKILL.mdというMarkdownファイルが1枚あれば成立します。プロトコルでもAPIでもなく、ファイル配置の取り決めというのが正確な理解です。
nameの64文字上限とanthropic・claudeが使えない予約語
Agent Skills仕様のFrontmatter定義では、nameは1〜64文字、使える文字はUnicodeの小文字英数字とハイフンのみ。先頭と末尾にハイフンは置けず、連続ハイフンも禁止で、親ディレクトリ名と一致させます。PDF-Processingは大文字で失格、pdf--processingは連続ハイフンで失格です。
仕様書だけを読んでいると踏む地雷が1つあります。Claude API側のドキュメントは、nameにXMLタグを含められないことに加え、予約語として「anthropic」「claude」を禁止しました。agentskills.ioの共通仕様にこの制限はありません。つまりclaude-deployはClaude Codeのファイルシステム配置で通っても、Skills APIへ上げる段階で弾かれます。社内スキルの命名規則から製品名の接頭辞は外してください。
descriptionの1024文字枠に呼び出し条件まで書く理由
descriptionは非空かつ最大1024文字。この欄が特殊なのは役割です。エージェントは起動時にnameとdescriptionだけをシステムプロンプトへ読み込み、依頼文と突き合わせて発動を判断します。説明文ではなく検索インデックスに近い扱いだと考えてください。
仕様書が示す良い例は「Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.」でした。何をするか（抽出・記入・結合）と、いつ使うか（PDF・フォーム・抽出という語が出たとき）の両方が入っています。悪い例は「Helps with PDFs.」の1文。発動条件が曖昧で、呼ばれるべき場面で呼ばれません。社内の稟議フロー用なら、稟議・決裁・申請という実際に使われる語を入れておきます。
SKILL.mdを1枚置いて動かす最小構成と確認すべき2つの挙動
最小のスキルは次の形で成立します。フロントマターをハイフン3つで囲み、name・descriptionを書き、その下にMarkdownで手順を書くだけです。
---
name: invoice-check
description: 受領した請求書の記載項目をそろえて検算します。請求書・支払・検収の確認を依頼されたときに使います。
---
# 請求書チェック
## 手順
1. 発行日・登録番号・税率区分の3点がそろっているか確認する
2. 小計と消費税額を再計算し、合計額と突き合わせる
3. 差異があれば金額と該当行を報告する
置いたあとで確かめる挙動は2つ。発動するかと、本文どおりに手順が走るかです。発動しない原因はほぼdescriptionにあり、本文を厚くしても改善しません。画面録画から手順を起こすCowork側の機能のように、作業記録からSKILL.mdを生成する経路も用意されています。
ディレクトリの作り方とscripts・references・assetsの置き分け基準
SKILL.md以外のファイルは任意です。ただし置き場所の慣例が決まっており、読み込まれ方がそれぞれ違います。
scriptsへ逃がす処理とSKILL.md本文へ残す指示の切り分け
ディレクトリ構成はこの形です。
invoice-check/
├── SKILL.md # 必須：メタデータと手順
├── scripts/ # 任意：実行可能なコード
├── references/ # 任意：詳細ドキュメント
└── assets/ # 任意：テンプレートや静的資源
切り分けの基準は、答えが決定的に決まる処理かどうか。scriptsのコードはbash経由で実行され、本体はコンテキストへ入らず標準出力だけが返ります。検算・形式変換・バリデーションのように毎回同じ答えを出すべき処理は、指示文で書き下すよりスクリプトへ寄せたほうが結果が安定し、トークンも減る。状況で判断が変わる部分だけをSKILL.md本文へ残してください。
referencesとassetsの置き分けとファイル参照1階層までの制約
referencesは必要時だけ読ませる詳細資料、assetsはテンプレートや画像、スキーマなどの静的資源です。仕様書はreferences配下の例としてREFERENCE.md（技術詳細）やFORMS.md（帳票テンプレート）を挙げ、1ファイルを小さく保つよう促しています。細かく割るほど読まれる範囲が狭まり、コンテキストを食いません。
参照の書き方には制約があります。スキルのルートからの相対パスを使い、SKILL.mdから1階層までに収めること。深い参照の連鎖は避けるよう明記されました。referencesの中でさらに別ファイルを指し、そこからまた別ファイルへ、という構造ではエージェントが目的のファイルへたどり着けません。索引はSKILL.mdが持ち、実体は1階層下に平たく並べます。
Progressive disclosureの3段階とトークン消費を抑える分割の実務
設計思想の中心が段階的な読み込みです。ここを外すと、スキルを増やすほど遅く高くなる構成を作ってしまいます。
メタデータ約100トークンがスキル数ぶん常時載る仕組みと上限設計
読み込みは3段階です。第1段階はメタデータで、nameとdescriptionが起動時に全スキルぶん載り、費用はスキルあたり約100トークン。第2段階が本文で、発動時にSKILL.mdの中身が入り、推奨は5000トークン未満。第3段階の資源は参照されるまで0トークンです。
| 段階 | 読み込み時点 | トークン費用 | 内容 |
|---|---|---|---|
| 1. メタデータ | 起動時（常時） | 1件あたり約100 | nameとdescription |
| 2. 指示本文 | スキル発動時 | 5000未満を推奨 | SKILL.mdの本文 |
| 3. 資源 | 参照された時のみ | 読むまで0 | scriptsやreferences |
計算してみます。社内へ50本配ると、1本も発動しなくても起動時点で約5000トークンが常に乗る。100本なら約1万トークンです。同梱ファイルをいくら増やしても費用は変わりませんが、スキルの本数だけは全員のコンテキストを毎回削ります。使われないスキルを棚卸しする運用が要る理由がここにあります。
本文5000トークン未満・500行以内へ収める分割の判断基準
仕様書はSKILL.mdを500行以内に保ち、詳細な参照資料を別ファイルへ移すよう指示しています。発動のたびに本文が丸ごと読まれる以上、長いSKILL.mdは毎回費用を払う構造だからです。
分割の判断は、その情報が毎回要るかどうか。手順の骨格と分岐条件は本文へ、エラーコード一覧・帳票の項目定義・APIのパラメータ表のように該当時だけ引く情報はreferencesへ送ります。目安の線は、発動ケースの半分未満でしか読まれない節なら外へ出すこと。Anthropicが公開している公式スキル群も、SKILL.mdを骨格に絞り帳票処理の詳細をFORMS.mdへ分けた構成です。ライセンスはApache 2.0が中心で、文書系4種（docx・pdf・pptx・xlsx）のみsource-availableという区分になっています。
Claude Codeでスキルを動かす手順と配置先4種の読み込み範囲
実装者がいちばん触るのはClaude Codeです。ファイルシステムベースで、アップロード操作が要りません。
personal・project・plugin・enterpriseの4配置と適用範囲
置き場所で読み込まれる範囲が変わります。Claude Code側のSkillsドキュメントが定義する配置は次のとおりです。
| 配置 | パス | 読み込まれる範囲 |
|---|---|---|
| Enterprise | 管理設定ディレクトリ配下 | 配布先の全ユーザー |
| Personal | ~/.claude/skills/ | そのマシンの全案件 |
| Project | .claude/skills/ | そのリポジトリ |
| Plugin | プラグイン配下のskills/ | プラグイン有効時 |
チームで共有するならProject配置、つまりリポジトリへコミットする形が基本。個人の作業癖はPersonalへ置きます。導入は手作業で構いません。
mkdir -p ~/.claude/skills/invoice-check
cp -r ./invoice-check/* ~/.claude/skills/invoice-check/
Claude Codeはスキルディレクトリの変更を監視するため、編集したファイルは再起動なしで反映されます。環境側の初期設定はClaude Codeの導入と権限設定の実務手順が前提です。
allowed-toolsで事前許可を渡す書き方と権限ルールとの優先順位
allowed-toolsは、そのスキルが動いている間だけ事前承認を与えるフィールドです。共通仕様では空白区切りの文字列と定義され、Experimentalの注記が付きます。対応状況は実装ごとに違う前提で使ってください。
Claude Codeでの書き方はallowed-tools: Bash(git add *) Bash(git commit *) Readのように、ツール名と引数パターンを空白で並べる形。効力はそのターン限りで、次のメッセージでは切れます。優先順位を誤ると事故になる。このフィールドは権限ルールより下位で、denyルールや確認要求ルールに上書きされる仕組みです。スキル側に許可を書いたから無条件で実行される、とは読まないでください。裏を返せば、組織のdenyルールはスキルの記述で迂回されません。
移植性を壊す独自フィールドの見分け方と共通6項目への寄せ方の手順
46製品対応という数字の実態を確認します。共通なのは形式であって、フィールドの全部ではありません。
共通仕様6フィールドとClaude Code独自フィールドの対応表
agentskills.ioが定めるフロントマターは6つだけ。必須がnameとdescription、任意がlicense・compatibility・metadata・allowed-toolsです。compatibilityは最大500文字で、対象製品・必要なシステムパッケージ・ネットワーク到達性といった環境要件を書く欄。metadataは文字列キーと文字列値のマップで、著者やバージョンを入れる想定になっています。
| 区分 | フィールド | 移植性 |
|---|---|---|
| 共通・必須 | name / description | 全対応製品で有効 |
| 共通・任意 | license / compatibility | 全対応製品で有効 |
| 共通・任意 | metadata | 全対応製品で有効 |
| 共通・実験的 | allowed-tools | 実装ごとに差あり |
| Claude Code独自 | model / context / agent | 他製品では無効 |
| Claude Code独自 | paths / shell / effort | 他製品では無効 |
Claude Codeは共通6項目に加え、実行モデルの指定・サブエージェント実行・対象パスの限定・シェル種別など多くの拡張を持ちます。手元の効率は上がる。ただしcontextやmodelを書いた時点で、そのスキルはClaude Code専用です。複数製品へ配る意図があるなら、共通6項目で書いたコアと製品別の制御層を別ディレクトリで管理する運用へ寄せます。梱包して配る段階の取り決めはAgent Plugins 1.0の梱包仕様が別に定めており、管轄が違います。
skills-ref validateと独自フィールド検出を通す検証手順
形式の検証にはリファレンス実装が用意されています。
skills-ref validate ./skills/invoice-check
これでフロントマターの妥当性と命名規則が検査されます。ただし共通仕様に無いフィールドの混入を、移植性の問題として警告してはくれません。配布前には次の検出を挟みます。
import pathlib, yaml
COMMON = {"name", "description", "license",
"compatibility", "metadata", "allowed-tools"}
for path in pathlib.Path("skills").rglob("SKILL.md"):
text = path.read_text(encoding="utf-8")
meta = yaml.safe_load(text.split("---")[1])
extra = set(meta) - COMMON
if extra:
print(path, "製品固有フィールド:", sorted(extra))
出力に挙がったスキルは、その製品でしか動きません。全社配布から外すか、共通部分だけを切り出して別スキルにするかをここで判断します。CIへ組み込めば、独自フィールドの混入を書いた本人が気づく前に止められる。
MCPとの役割分担とSkillsへ寄せてはいけない処理の切り分け
同じエージェント拡張でも、SkillsとMCPは解いている問題が違います。両方を入れる現場ほど、この線が曖昧なまま設計が崩れます。
手順書はSkills・外部接続はMCPへ寄せる切り分けの具体例
Skillsが運ぶのは手順と知識、MCPが運ぶのは接続と機能です。基幹システムから受注データを取る処理はMCPサーバの担当で、取得後にどの順序で検算しどの条件でエスカレーションするかがSkillsの担当。MCPの仕組みとMCPサーバーの作り方で扱った標準規格と、この記事のスキル形式は競合しません。
迷ったら、認証情報が要るかどうかで分けてください。接続先の資格情報や権限設計が絡む処理はMCP側へ。MCPでの外部ツール接続とtool定義・認可の設計で整理したとおり、そこは権限モデルの領域であり、Markdownの手順書に書く内容ではありません。社内の申請フローや帳票の読み方のように、権限ではなく業務知識で決まるものがスキル側です。
Claude API経由のネットワーク遮断が設計を左右する場面と回避策
実行環境の制約はサーフェスごとに違い、これが設計を左右します。Claude API上のスキルはサンドボックスコンテナで動き、ネットワーク到達性がありません。実行時のパッケージ追加も不可で、コード実行ツールに同梱済みの依存だけが使えます。外部APIを叩くスクリプトを同梱したスキルは、Claude Codeで動いてAPIでは動きません。
Claude Codeは対照的に、ユーザーのマシン上の他プログラムと同じネットワーク権限を持ちます。claude.aiは設定次第で全開・部分・遮断のいずれにもなる。回避策は素直で、外部到達が要る処理はスキルへ同梱せずMCPサーバ側へ出します。そのうえでcompatibility欄に必要な環境を書き残すと、配布先で動かない理由が読み手に伝わります。
受託開発の現場でスキル化を見送る業務条件とサーフェス選定の失敗例
ここからは判断の話です。スキル化できることと、スキル化すべきことは分けて考えます。
claude.aiへ配ると管理者が回収できない共有スコープの落とし穴
共有スコープはサーフェスごとに完全に別です。claude.aiのカスタムスキルは利用者ごとの個人資産で、メンバーがそれぞれ自分でアップロードする。組織全体への配布も管理者による一元管理もできません。Claude APIはワークスペース単位で共有され、メンバー全員が同じスキルへ到達します。Claude Codeはファイルシステムとプラグインが配布経路です。
ここで起きる失敗は決まっています。claude.aiで作ったスキルを全員に配って回り、数か月後に手順が変わって、誰がどの版を持っているか分からなくなる。回収も更新も管理者側からはできません。全社配布が前提ならclaude.aiは検証用と割り切り、配布はプロジェクト配置かAPIワークスペースへ寄せます。業務手順のスキル化と社内展開をまとめて設計する段階では、生成AI開発・AI受託開発のように実装と運用設計を通しで見る体制のほうが、版管理の破綻を避けられます。
ZDR対象外という保持条件からスキル化を見送るべき業務の線引き
見送る条件を言い切ります。ゼロデータ保持の契約で守っている業務は、スキル化しません。Agent SkillsはZDRの対象外で、スキル定義と実行データは通常のデータ保持ポリシーに従って保持されるとドキュメントに明記されています。保持されない前提で設計した業務の手順書を、保持される場所へ書き写す形になるためです。
外部から入手したスキルを検証せず本番へ入れる運用も見送ります。スキルはClaudeへ新しい能力を与える仕組みで、悪意ある内容は記載された目的と違う形でツールを呼び出せる。公式ドキュメントも、信頼できる出所のスキルだけを使い、やむを得ない場合はSKILL.mdとスクリプトと同梱資源をすべて監査するよう求めています。外部URLからデータを取るスキルは特に危険で、取得先の内容が後から変わる経路が残ります。社内配布のスキルは、依存の棚卸しを含めてコードと同じレビュー工程へ載せてください。
よくある質問
Agent Skillsの導入検討でよく挙がる質問を、一次情報の記述に沿って整理します。
Agent SkillsとMCPは何が違いますか？
渡すものが違います。Agent Skillsはエージェントへ手順書と業務知識を渡すファイル形式、MCPはエージェントを外部のツールやデータソースへ接続するプロトコルです。競合せず併用します。基幹システムへの接続はMCPサーバ、取得データの処理順序や判断基準はスキル、という分担が実装上の目安。認証情報や権限設計が絡む処理はMCP側へ寄せてください。
Agent Skillsはどのツールで使えますか？
2026年9月18日時点で46製品が対応しています。Claude CodeとClaude本体のほか、ChatGPTおよびCodex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro、Goose、OpenCode、Roo Code、Tabnineなどが並びます。Spring AI、Laravel Boost、Pulumi Neo、Snowflake Cortex Code、Databricks Genie Codeのようにフレームワークや基盤製品側の対応も進みました。最新の一覧は公式のクライアント一覧ページで確認できます。
スキルを作るのにプログラミングは必要ですか？
不要です。最小構成はSKILL.md1枚で、YAMLフロントマターにnameとdescriptionを書き、その下へMarkdownで手順を書けば動きます。scriptsディレクトリへ実行可能なコードを置く構成は任意で、検算や形式変換のように毎回同じ答えを返すべき処理がある場合に使う。業務手順の文書化ができれば、最初の1本は作れます。
claude.aiで作ったスキルはClaude Codeでも使えますか？
自動では同期しません。カスタムスキルはサーフェスをまたいで共有されず、claude.aiへ上げたものはAPIでは使えず、API経由で登録したものはclaude.aiに現れない。Claude Codeはファイルシステムベースで、その両方と独立しています。同じスキルを複数の場所で使うなら、それぞれへ個別に配置する前提で運用設計を組んでください。
社外から入手したスキルをそのまま使っても安全ですか？
監査なしでの本番投入は避けてください。公式ドキュメントは、自作したものかAnthropic提供のものだけを使うよう求めています。スキルは指示とコードでClaudeに新しい能力を与えるため、悪意ある内容はツールを想定外の形で呼び出せる。とくに外部URLからデータを取得するスキルは、取得先の内容が後から差し替わる経路が残ります。ソフトウェアの導入と同じ基準で審査してください。
関連記事
- MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方：接続側を担うもう1つの標準
- Agent Plugins 1.0とは？梱包仕様とクライアント準拠要件：作ったスキルを配る梱包層
- Claude Record a skillとは？画面録画でスキルを自動生成する機能：SKILL.mdを起こす手段
- Claude Codeの使い方｜導入から権限とCLAUDE.md設定まで：配置先となる環境の初期設定
- AIエージェントとは？生成AIとの違い・仕組みと業務に組み込む判断基準：スキルを載せる前段の全体像
