AnthropicのAgent Skillsの仕組み

目次
  1. 要点
  2. 時系列
  3. 仕組み
    1. スキルのフォルダの中身
    2. 段階ごとの読み込み
  4. 使いどころと条件
  5. 取り違えやすい点
  6. 用語
  7. 未確認の事項
  8. 注
  9. 出典
  10. 更新記録
  11. 関連記事

Anthropicのドキュメントは、指示・メタデータ・任意のリソースをまとめ、Claudeが関連する場面で自動で使う「Agent Skills」の仕組みを説明している⁠[1]。

要点

要点
項目内容資料
中身SKILL.md(YAMLのフロントマターとMarkdownの本文)と、任意のスクリプト・参照資料・素材⁠[9]
読み込み方起動時に名前と説明を読み、依頼に合えばSKILL.mdの本文、必要なときに付属のファイルを読む⁠[1]
使える製品claude.ai、Claude API、Claude Codeなど⁠[1]
規格agentskills.ioでオープンな規格として公開⁠[5]
安全の扱い信頼できる提供元のスキルだけを使うよう案内⁠[1]

目次へ

時系列

時系列
日付区分内容資料
2025年10月16日公開Agent Skillsを説明する技術記事を公開した⁠[7]
2025年12月18日その他Agent Skillsをオープンな規格として公開した⁠[7]

目次へ

仕組み

スキルのフォルダの中身

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]。

目次へ

用語

SKILL.md
スキルのディレクトリに置く必須のファイルで、YAMLのフロントマターの後にMarkdownの内容を置く⁠[9]。
段階的な開示(progressive disclosure)
最初に全部を読まず、必要に応じて段階ごとに情報を読み込む仕組み⁠[1]。
コード実行ツール(code execution tool)
APIでスキルを使うのに要る道具で、スキルはそのcontainerの中で動く⁠[1]。
MCP(Model Context Protocol)
Claudeを外部のサービスとデータの源につなぐ仕組み⁠[5]。

目次へ

未確認の事項

  • claude.aiでアップロードできるスキルの大きさの上限
  • claude.aiとClaude Codeで使えるスキルの数の上限
  • 日本語で書いたdescriptionの扱い

注

  • 〔注1〕ヘルプセンターは、APIの利用者にはベータで提供していると記載している⁠[5]。
  • 〔注2〕ヘルプセンターは、Free・Pro・Max・UltraのプランでもCustomize > Skillsから自分のスキルをアップロードできると記載している⁠[6]。
  • 〔注3〕ヘルプセンターとClaude Codeのドキュメントは、claude.aiで有効にしたスキルが、同じアカウントでサインインしたClaude Codeにも読み込まれると記載している⁠[4、6]。

出典

更新記録

  • 2026年11月18日12時32分:掲載した。

目次へ

最終確認:2026年11月18日。この記事は、この時点で出典の資料に書かれていた内容をもとにした解説です。機能・料金・提供範囲は変わることがあります。利用の前に、出典の公式資料で最新の内容を確かめてください。広告・紹介リンクは置いていません。