AnthropicのAgent Skillsの仕組み
Anthropicのドキュメントは、指示・メタデータ・任意のリソースをまとめ、Claudeが関連する場面で自動で使う「Agent Skills」の仕組みを説明している[1]。
要点
時系列
仕組み
スキルのフォルダの中身
Agent Skillsの規格の仕様によると、スキルは少なくともSKILL.mdのファイルを含むディレクトリである[9]。実行できるコードを入れるscripts/、文書を入れるreferences/、テンプレートや素材を入れるassets/は任意で置く[9]。SKILL.mdには、YAMLのフロントマターの後にMarkdownの内容を書く[9]。
フロントマターで必須の項目はnameとdescriptionである[9]。nameは1〜64字で、小文字の英数字とハイフンだけを使い、親ディレクトリの名前と一致させる[9]。descriptionは1〜1024字で、スキルが何をし、いつ使うかを書く[9]。任意の項目にはlicense・compatibility・metadata・allowed-toolsがあり、仕様はallowed-toolsを実験的(Experimental)な項目としている[9]。
Anthropicのドキュメントは、Claudeで使うnameの条件に、XMLタグと予約語(anthropic、claude)を含めないことを加えている[1]。
段階ごとの読み込み
Anthropicのドキュメントによると、スキルは、Claudeがファイルシステム・bash・コードの実行を使えるコード実行の環境で動く[1]。この作りで段階的な開示(progressive disclosure)ができ、Claudeは最初に全部を読まず、必要に応じて段階ごとに情報を読み込む[1]。
第1段階はメタデータで、フロントマターのnameとdescriptionが起動時にシステムプロンプトに入る[1]。量は1スキルあたり約100トークンである[1]。スキルが使われるまでコンテキストを占めるのはこの2つだけで、多くのスキルを入れてもコンテキストの負担にならないと説明している[1]。
第2段階では、依頼がdescriptionに合うと、ClaudeがbashでSKILL.mdを読み、その本文がコンテキストに入る[1]。ドキュメントの表は、この段階の量を5,000トークン未満としている[1]。
第3段階は付属のファイルで、参照資料は読んだときにコンテキストに入り、スクリプトはbashで実行されて出力だけがコンテキストに入る[1]。言い換えると、読まれないファイルとスクリプトのコードそのものは、コンテキストを使わない[1]。
規格のサイトは、この3つの段階を発見(Discovery)・起動(Activation)・実行(Execution)と呼んでいる[8]。Anthropicの技術記事は例として、PDFのスキルに入ったPythonのスクリプトがフォームの項目を取り出し、ClaudeはスクリプトもPDFもコンテキストに読み込まずに実行できると説明した[7]。
使いどころと条件
Anthropicが用意したPowerPoint・Excel・Word・PDFのスキルは、claude.ai・Claude API・Claude Platform on AWS・Microsoft Foundryで使える[1]。Microsoft FoundryではHosted on Anthropicの配備が要る[1]。Claude Codeは自作のスキルに対応し、これらの文書作業のスキルには対応しない[1]。
Claude Codeの自作のスキルは「~/.claude/skills/」(個人)か「.claude/skills/」(プロジェクト)に置き、APIへのアップロードは要らない[1]。Claude Codeのドキュメントは、既定では利用者もClaudeもスキルを呼び出せ、利用者は「/skill-name」の形で直接呼べると記載している[4]。フロントマターに「disable-model-invocation: true」を書くとClaudeが自分で呼ぶのを止め、「user-invocable: false」を書くとClaudeだけが呼べる[4]。Claude Codeのスキルは規格に従い、呼び出しの制御・サブエージェントでの実行・動的な文脈の差し込みを独自に加えている[4]。
Claude APIでは、要求のcontainerのパラメータにskill_idを指定し、コード実行ツールと組み合わせる[1]。自作のスキルはSkills API(/v1/skills)でアップロードし、ワークスペースのすべてのメンバーが使える[1]。APIのガイドは、1回の要求で指定できるスキルを最大20、アップロードの大きさを最大30 MB(全ファイルの合計、圧縮前)と記載している[3]。Skills APIはベータを終え、ベータのヘッダーは要らない〔注1〕[3]。
claude.aiでは、自作のスキルのフォルダをZIPにまとめ、Customize > Skillsからアップロードする[6]。ドキュメントの概要は、自作のスキルを使えるプランを、コード実行を有効にしたPro・Max・Ultra・Team・Enterpriseとしている〔注2〕[1]。
実行の環境は製品で違う[1]。Claude APIではネットワークに接続できず、実行中にパッケージを入れられない[1]。claude.aiでは利用者と管理者の設定で接続が全部・一部・無しのどれかになり、Claude Codeでは利用者のコンピュータのほかのプログラムと同じ接続を持つ[1]。
データの扱いについて、Agent Skillsはゼロデータ保持(ZDR)の取り決めの対象外で、スキルの定義と実行のデータはAnthropicの標準のデータ保持の方針で保持される[1]。Claude Enterpriseの組織は、claude.aiとClaude Coworkに上げた自作のスキルの内容の検査を有効にでき、Skills APIとClaude Consoleで上げたスキルは検査の対象外である[1]。
書き方のガイドは、SKILL.mdの本文を500行未満に保ち、参照のファイルはSKILL.mdから1段の深さにとどめるよう案内している[2]。descriptionはシステムプロンプトに差し込まれるので、三人称で書くよう求めている[2]。
取り違えやすい点
Anthropicのヘルプセンターは、スキルとほかの機能を区別している[5]。プロジェクトはその中のチャットで常に読み込まれる背景知識で、スキルは必要なときに働く手順である[5]。MCPはClaudeを外部のサービスとデータにつなぎ、スキルは作業の進め方の知識を与えるもので、両方を一緒に使える[5]。カスタム指示はすべての会話に当たり、スキルは関連するときだけ読み込まれる[5]。
Claude Codeのドキュメントによると、allowed-toolsは、スキルを呼び出したターンのあいだ挙げた道具の許可を与えるもので、使える道具を制限しない[4]。Anthropicのドキュメントの概要は、自作のスキルが製品の間で同期されず、Claude Codeのスキルはclaude.aiとAPIのどちらとも別だと記載している〔注3〕[1]。
Anthropicは、スキルを自分で作ったものかAnthropicから得たものに限るよう案内している[1]。悪意のあるスキルは、説明した目的に合わない形でClaudeに道具を呼ばせたり、コードを実行させたりできる[1]。信頼できない提供元のスキルを使うときは、SKILL.md・スクリプト・画像を含む付属のファイルをすべて調べるよう求めている[1]。
外部のURLからデータを取ってくるスキルは、取ってきた内容に悪意のある指示が入りうるので特に危険だと、同じドキュメントは記載している[1]。ヘルプセンターは、主な危険にプロンプトインジェクションとデータの持ち出しを挙げた[6]。
用語
未確認の事項
- claude.aiでアップロードできるスキルの大きさの上限
- claude.aiとClaude Codeで使えるスキルの数の上限
- 日本語で書いたdescriptionの扱い
注
出典
- [1]Anthropic PBC『Agent Skills』(公開日不明、2026年11月18日確認)
- [2]Anthropic PBC『Skill authoring best practices』(公開日不明、2026年11月18日確認)
- [3]Anthropic PBC『Using Agent Skills with the API』(公開日不明、2026年11月18日確認)
- [4]Anthropic PBC『Extend Claude with skills』(公開日不明、2026年11月18日確認)
- [5]Anthropic PBC『What are skills?』(公開日不明、2026年11月18日確認)
- [6]Anthropic PBC『Use skills in Claude』(公開日不明、2026年11月18日確認)
- [7]Anthropic PBC『Equipping agents for the real world with Agent Skills』(2025年10月16日公開、2026年11月18日確認)
- [8]Agent Skills(agentskills.io)『Agent Skills Overview』(公開日不明、2026年11月18日確認)
- [9]Agent Skills(agentskills.io)『Specification』(公開日不明、2026年11月18日確認)
更新記録
- 2026年11月18日12時32分:掲載した。
最終確認:2026年11月18日。この記事は、この時点で出典の資料に書かれていた内容をもとにした解説です。機能・料金・提供範囲は変わることがあります。利用の前に、出典の公式資料で最新の内容を確かめてください。広告・紹介リンクは置いていません。
