Agent Skills

Agent Skills は、エージェントの機能を拡張するモジュール式の能力をパッケージ化するための形式であり、Anthropic が Claude 向けに文書化している。スキルパッケージは、エージェントのベンダー以外の当事者によっても作成・公開されている。 Google のデベロッパーリレーションズチームは、エージェントスキルが、モデルの固定された学習知識と変化の速いライブラリや SDK との間のギャップを埋める、きわめて軽量でありながら潜在的に効果的な方法として浮上してきたと書き、そのギャップに対して SDK のメンテナーなら誰でもできることを示そうとしている。各スキルは、指示、メタデータ、そしてスクリプトやテンプレートなどの 任意のリソースをひとまとめにしたもので、モデルは関連する場面でこれを自動的に使う。ベンダーのドキュメントは、スコープと 永続性の観点からスキルをプロンプトと区別している。プロンプトは単発のタスクのための会話レベルの指示であるのに対し、 スキルはオンデマンドで読み込まれる再利用可能なファイルシステムベースのリソースであり、同じガイダンスを会話のたびに 繰り返す必要がなくなる。挙げられている利点は、ドメイン固有のタスクに向けてモデルを特化させること、ガイダンスを 繰り返すのではなく一度作れば済むこと、そして複数のスキルを組み合わせて多段階のタスクに使えることである。

Anthropic 自身によるこの形式のエンジニアリング解説（Agent Skills でエージェントを現実世界に対応させる）は、 この形式を欠陥への対応ではなく能力への対応として位置づけている。汎用エージェントが完全なコンピューティング環境を 操作できるようになると、残る問いは、ドメインの専門知識を合成可能に、スケーラブルに、そして可搬的に与えるにはどうすれば よいか、になる。その解説は、スキルの構築を新入社員のためのオンボーディングガイドの作成になぞらえ、この形式が置き換える 代替案はユースケースごとに個別に設計されたエージェントを構築することだと論じている。この記事に 2025 年 12 月 18 日付で 追加された注記は、Agent Skills がその後、クロスプラットフォームの可搬性のためのオープン標準として公開されたことを 記録している。製品発表（Agent Skills の紹介）にも同日付の注記があり、それと並んでさらに 2 つの追加、 すなわちスキルの組織全体での管理と、パートナーが構築したスキルを掲載するディレクトリを記録している。

Anthropic が Claude 向けに文書化しているとおり、この形式は設計上ファイルシステムベースである。スキルは Claude の 仮想マシン環境内のディレクトリとして存在し、Claude は通常のシェルコマンドでそれらとやり取りする。SKILL.md を読んで その指示をコンテキストに取り込み、指示が参照している場合にはさらにファイルを読み、同梱されたスクリプトはシェルを通じて 実行するため、コンテキストウィンドウに入るのはスクリプトの出力だけで、コードそのものは決して入らない。他のハーネスは 別の手段でスキルにアクセスする。たとえば Google の評価では、モデルに activate_skill ツールと、ドキュメントを ダウンロードするための fetch_url ツールが与えられた。

用法

すべてのスキルには、name と description という 2 つの必須フィールドを持つ YAML フロントマターを備えた SKILL.md ファイルが必要である。ドキュメントはそれぞれの制約を定めている。名前は最大 64 文字で、小文字、数字、ハイフンに限られ、 XML タグや予約語を含んではならない。説明は空でない最大 1024 文字の文字列で、こちらも XML タグを含んではならない。 説明には、そのスキルが何をするのかと、いつ使うべきなのかの両方を書かなければならない。モデルがスキルを起動するかどうかを 判断する際に、リクエストと照合するのがこの説明だからである。

内容は 3 つのレベルに整理され、それぞれ異なるタイミングで読み込まれる。ドキュメントはこの構成を 段階的開示（Progressive Disclosure） と呼んでいる。メタデータは常に読み込まれ、そのコストはスキル 1 つあたり約 100 トークンとされている。SKILL.md の本文はスキルが起動されたときに読み込まれ、その予算は 5,000 トークン未満と されている。同梱リソースは読まれるまで一切コストがかからない。ドキュメントに記された帰結として、コンテキスト上の ペナルティなしに多数のスキルをインストールでき、またスキルは包括的な API ドキュメントや大規模なデータセットといった 大量の資料を同梱でき、それらは使われない限りコンテキストに計上されない。

ベンダーのエンジニアリング記事は、この構成を具体例、すなわち Claude の文書編集能力を支える PDF スキルで説明している。 その SKILL.md は同梱された 2 つのファイル、reference.md と forms.md を参照しており、記事によれば、フォーム入力の 指示を forms.md に移した理由は、モデルが実際にフォームを入力するときにだけそのファイルを読むことを見越して、スキルの 中核を簡潔に保つためである。同じスキルには、PDF を読み込んでフォームフィールドを抽出する Python スクリプトが同梱されて おり、モデルはスクリプトも PDF もコンテキストに入れることなくそれを実行できる。記事はこの構成を 2 つの根拠で正当化して いる。すでにコードが行っている処理をトークンを生成して行うのははるかに高コストであること、そして多くの用途では コードだけが提供できる決定性が必要であることである。

作成方法について、この記事は評価から始めることを推奨している。代表的なタスクでエージェントを走らせてどこでつまずくかを 見つけ、何が必要になるかを予想するのではなく、観察されたギャップに対してスキルを段階的に構築していく、というものである。 SKILL.md が扱いにくくなったら個別の参照ファイルに分割することを勧め、文脈が互いに排他的であるか、一緒に使われることが まれな場合は、それらの経路を分けておくことでトークン使用量が減ると付け加えている。また、同梱されたコードは実行可能な ツールとドキュメントの両方の役割を果たすため、スキルはある特定のスクリプトがそのどちらなのかを明確にすべきだと指摘する。 name と description には特に注意を払うよう求めており、その理由は、モデルがそもそもスキルを起動するかどうかを 決めるのにこれらを使うからである。最後の提案は、作業が進むにつれて成功したアプローチや繰り返される誤りをモデル自身に スキルとして記録させ、モデルが道を外れたときには自己反省を求める、というものである。

利用可能性はベンダーの製品ごとに異なる。API では、スキルにはコード実行ツールが必要で、コンテナパラメータ内の skill_id によって選択される。PowerPoint、Excel、Word、PDF 向けの構築済みドキュメントスキルがあり、カスタムスキルは Skills API を通じてアップロードされ、ワークスペース全体で共有される。Claude Code では、 カスタムスキルはファイルシステムベースでアップロードの必要がなく、個人用またはプロジェクト用のディレクトリに配置される。 一方、構築済みドキュメントスキルはそこでは利用できない。claude.ai では両方が動作し、カスタムスキルは zip ファイルとして アップロードされ、一元管理されるのではなくユーザーごとに個別である。ドキュメントは、カスタムスキルが組織全体で共有されず、 管理者が一元管理することもできないこと、そして claude.ai はカスタムスキルの一元的な管理者管理や組織全体への配布を サポートしていないことを述べている。これは、スキルの組織全体での管理が追加されたと記録する製品発表の 2025 年 12 月の 注記と整合しないまま残っている。2 つの情報源は異なることを述べており、どちらも相手との前後関係を示す日付を記していない。 エンジニアリング記事は、公開時点でこの形式が Claude.ai、Claude Code、Claude Agent SDK、 Claude Developer Platform でサポートされていたと述べている。

製品発表は、それぞれの利用面へのアクセス方法を補足している。Claude アプリでは、この形式は Pro、Max、Team、Enterprise の ユーザーが利用でき、Team と Enterprise では管理者がまず組織全体で有効にする必要があるとされる。起動は手動で選ぶのではなく 自動であり、発表によれば、スキルは Claude が作業する際の思考の連鎖（chain of thought）の中に現れる。Developer Platform では、 スキルを Messages API のリクエストに追加でき、/v1/skills エンドポイントによってカスタムスキルのバージョン管理と管理を プログラムから制御でき、スキルには Code Execution Tool のベータ版が必要とされる。このツールは、スキルの実行に必要な 安全な環境を提供するものと説明されている。Claude Code では、スキルは anthropics/skills マーケットプレイスからプラグイン 経由で、または ~/.claude/skills に手動で配置してインストールされ、バージョン管理を通じてチームと共有される。

ある実務家の記録は、同じ構造上の助言に逆方向から到達しており、ここにある情報源の中でそれを検証したと報告している唯一の ものである。mercari-pm-agent の設計 — Claude Code Skills と MCP で PM のワークフローを自動化する は、プロダクトマネージャーのワークフローを端から端まで担うスキルの 構築について述べ、最初はすべての定義を 1 つの SKILL.md にまとめたが、別の評価用スキルによるスコアリングを通じて、 ファイルが長くなるほど出力の精度が悪化することがわかったと報告している。著者の対応は、振る舞いの定義（何をどの順序で 行うか）を、references/ ディレクトリに置いた参照データやテンプレートから分離することであり、この構造の変更だけで スコアが明確に改善したと報告している。記事はこれを、ソフトウェアエンジニアリングにおける関心の分離をプロンプト設計に 応用したものと位置づけ、根底にある問題を、長いコンテキストの中ほどにある情報にモデルが適切に注意を向けられないという、 しばしば「Lost in the Middle」と呼ばれる現象に結びつけている。また、英語の指示のほうが Claude では精度が高くなる 傾向があるという理由で、SKILL.md を英語で書いているとも記している。この記録が上記のベンダーの助言に付け加えるのは、 別の規則ではなく、それに従う理由である。ベンダーはファイルが扱いにくくなったら分割するよう勧めているが、この著者は そうしなかった場合のコストを測定したと報告している。

同記事のその他の設計上の主張は、スキルの指示をどう整理するかではなく、指示が何を禁じるべきかに関するものである。 記事の立場は、業務ワークフローに LLM を組み込む際に最も危険なリスクは、もっともらしいが根拠のない出力、つまりデータが 存在しないところでモデルがそれらしい数値を生み出すことであり、これはモデルに嘘をつくなと言うだけでは解決できない、 というものである。スキルは、データの欠落を認識したときにどう振る舞うべきかを明示しなければならない。そこで使われている 規則は、未確認のデータには「提供なし」または「要検証」のラベルを付けなければならず、数値や情報源を決して捏造しては ならない、というものであり、あわせてエージェントが完全性を推測することを禁じる指示があり、ユーザーからの明示的な確認が あって初めて次のステップへ進めるようになっている。著者のまとめは、スキルの設計は振る舞いの仕様を書くことに近く、 モデルがしてはならないことを明確に定義するほうが、命令するよりも直接的に精度を高める、というものである。

2 つ目の実務家の記録は、個人の作者によるものではなく、組織の共有インフラとして使われるこの形式について述べている。 Zalando におけるエージェント型エンジニアリング：現状のスナップショット は、Zalando における一元化されたスキル集を 報告している。これはプラグインにグループ化され、分野（記事はデータ、エンジニアリング、フロントエンド、SRE を挙げている） やプログラミング言語をまたいで共通のタスクや関心事に対応している。記事によれば、新しいプラットフォームツールや、 マルチアーキテクチャビルドのようなインフラストラクチャの慣行の導入をチームに案内する移行用スキルが、広く人気のある種類 である。配布は、管理された構成設定か、必要なシンボリックリンクをインストールする CLI コマンドによって行われ、記事は その理由を、プラグインマーケットプレイスをサポートしていないエージェントがあるためだとしている。

この記録が配布の仕組みを超えて付け加えているのは、幅広い貢献を促したことによると著者が考える二次的な効果である。 すなわち、このスキル集は組織全体でベストプラクティスを発見し広める手段となった。たとえば CI/CD パイプラインでプラグインの 構文を検証することや、スキルとスクリプトの境界をどこに置くべきかといった問題についてであり、記事の例は OAuth トークンの 生成がどちらに属するかである。独自のスキルを書くチームは、このスキル集を参考やヒントとして使っているという。これらは 1 つの組織の実践についての著者自身の観察であり、評価は報告されていない。

スキルの作成は、それ自体のためのスキルによって支援されている。発表は skill-creator スキルについて述べており、これは ワークフローについて質問し、フォルダ構造を生成し、SKILL.md ファイルを整形し、リソースを同梱するといった対話的な ガイダンスを提供し、手作業でのファイル編集を必要としない。これはこの形式をそれ自体に適用したものであり、スキルを書く ための手続き的知識がスキルとしてパッケージ化されている。

3 つ目の実務家の記録は、ここでこの形式が現れる中で最も小さな規模、つまりチームや組織ではなく開発者 1 人の事例である。 本当に「ポチッ」で全部できるのか？ — 保守的な開発者が AI エージェントでプロダクトをリリースして気づいたこと は、同じプロンプトを打ち直すのが面倒になった時点で、 繰り返し使うプロンプトをスキルとしてテンプレート化したと報告しており、その例は、コミットされていない変更を分析して そのテストを書くという定番の依頼である。そして、そうしたスキルの正体は単なるプロンプトではなく、エンジニアのノウハウを コーディング規約に移植したものだと述べている。2 つ目の使い方は、他人が書いたスキルを使うものである。バックエンド 開発者である著者は、サードパーティの SEO スキルを自分のサイトに対して実行して改善点のリストを作り、そのリストを エージェントに渡してソースに適用させ、このループをおよそ週 1 回繰り返した。そこから導かれた観察は、この形式が最も 役立つのは自分の専門外の領域だということであり、これは Google の記録が変化の速い SDK について行っている知識ギャップの 議論に、モデルの学習データのカットオフからではなく開発者自身の専門性の側から到達したものである。この記録は評価を 報告しておらず、エージェントとして Claude Code を挙げている以外に、どのハーネスの機能セットについて述べているのかを 特定していない。

この形式は Anthropic の製品に限られない。ChatGPT と OpenAI Codex でスキルを構築するための OpenAI のドキュメントは、同社のスキルがオープンなエージェントスキル標準に基づいていると述べ、同じ形を説明している。 すなわち、name と description を含まなければならない SKILL.md ファイルを持つディレクトリに、任意の scripts/、 references/、assets/ ディレクトリと、UI メタデータ、起動ポリシー、ツール依存関係のための任意の agents/openai.yaml ファイルを加えたものである。段階的開示についても説明しており、ChatGPT と Codex は各スキルの 名前と説明から始め、スキルを使うと判断したときにだけ SKILL.md 全体を読み込む。さらに Codex 固有の上限を付け加えている。 初期のスキル一覧は、Codex では各スキルのファイルパスも含むが、モデルのコンテキストウィンドウの最大 2%、ウィンドウが 不明な場合は 8,000 文字までしか使わず、多数のスキルがインストールされている場合、Codex はまず説明を短縮し、一部の スキルを省略することもある。起動は、プロンプトでスキル名を挙げる明示的なものと、タスクがスキルの description に 一致したときの暗黙的なものがあり、agents/openai.yaml で allow_implicit_invocation: false を設定すると、明示的な 起動は有効なまま暗黙的な起動がオフになる。Codex は、リポジトリ内の場所（作業ディレクトリからリポジトリのルートまでの 各ディレクトリにある .agents/skills）、ユーザー用の場所、管理者用の場所、そして Codex に同梱されたセットからスキルを 読み込む。ドキュメントはこれらの場所を作成とローカルでの発見のためのものとして扱い、スキルを他者に配布するには、 複数のスキルを MCP サーバーへの接続とともに同梱できるプラグインを案内している（Agent Plugins と比較 されたい）。そのベストプラクティスの一覧は、各スキルを 1 つの仕事に集中させること、決定的な振る舞いや外部ツールが 必要でない限りスクリプトよりも指示を優先すること、明示的な入力と出力を持つ命令形の手順を書くこと、そしてスキルの説明に 対してプロンプトをテストし、正しく起動されることを確認することである。

研究における捉え方

学術文献は、この用語をどの製品のファイル形式よりも広い意味で使っている。 エージェントスキルに関する包括的サーベイ：分類、技法、応用 は、エージェントスキルを、タスク固有の制約のもとでツール、 メモリ、実行時コンテキストを調整する再利用可能な手続き的アーティファクトと定義し、スキルを 3 つの部分からなる組として 形式化している。エージェントが読み込んで従うことのできるルートの指示文書、参照文書、テンプレート、実行可能なスクリプト などの補助リソースの集合、そしてスキルをいつ取得して適用すべきかを定める適用条件であり、最後のものはメタデータ、 自然言語による説明、または埋め込みとして表現される。このサーベイは、すべてのシステムでこの組が完全に具体化されている 必要はないと注記している。上で述べた形式に照らして読めば、SKILL.md の本文は指示文書に、同梱ファイルはリソースに、 フロントマターの description は適用条件に対応する。サーベイ自体は、自らが扱う手法が進化させるアーティファクトの中に SKILL.md ファイルやスキルフォルダを挙げているが、概念をそれらに結びつけてはいない。

このサーベイによれば、スキルが必要とされる理由は、同サーベイが 手続き的ギャップ と呼ぶものにある。ツールに アクセスできても、ある能力をいつ呼び出すべきか、ツールをどう連携させるべきか、失敗をどう扱うべきか、出力をどう検証 すべきかはわからない。サーベイはエージェントを高レベルのプランナーとし、スキルをその下の運用層として位置づけ、スキルは トリガー、順序づけ、フォールバック、落とし穴といった状況に即したノウハウを符号化するのに対し、ツールは操作を公開する だけだという理由で、スキルを生のツールや MCP サーバーから区別している。また、ツール中心ではないスキル、たとえば主に モデル自身の知識に頼りつつも場当たり的なプロンプティングを超える構造を提供するレビューチェックリストのようなものも 認めている。

ベンダーのドキュメントがスキルの書き方と読み込み方を説明しているのに対し、このサーベイは研究をライフサイクルに沿って 整理している。スキルがどう表現されるか（リソースが何を含むかによって、テキストベース、コードベース、またはハイブリッド）、 どう獲得されるか（人間の専門家から、エージェント自身の過去の実行から、現在のタスクのためにオンデマンドで、または外部 コーパスから）、大規模なプールからどう取得・選択されるか、そして存在した後にどう進化するか（改訂、検証、共有 リポジトリを通じた伝播、実行時のガバナンス）である。サーベイが特定する問題は、作成上の問題ではなくライフサイクル上の 問題である。有用な手続きがうまくルーティングされないままになる弱いトリガー条件、スキルの主文書と添付スクリプトの間の 乖離、ライブラリがキュレーションできるよりも速く低品質なスキルが蓄積すること、そしてスキルを追加するのは得意でも、 安全に書き換えたり廃止したりするのははるかに苦手なシステムである。

適用される場面

この形式が当てはまるのは、エージェントがドメインの専門知識（ワークフロー、コンテキスト、ベストプラクティス）を必要とし、 それがなければ会話のたびに言い直さなければならない場合である。Anthropic が文書化している構成では、モデルにファイル システムへのアクセスとコマンド実行能力を与える実行環境が前提となる。

ドキュメントは、この形式が伴うセキュリティ上の前提について率直である。スキルは信頼できる情報源からのものだけを使う べきである。スキルは指示とコードを通じてモデルに新しい能力を与えるものであり、悪意のあるスキルは、表明された目的と 一致しない形でツールを呼び出したりコードを実行したりするようモデルに指示できるからである。ドキュメントは、同梱された すべてのファイルを監査するよう勧め、取得したコンテンツ自体に悪意のある指示が含まれている可能性があるため、外部 URL から データを取得するスキルは特に危険であるとし、 インストールをソフトウェアのインストールと同様に扱うよう推奨している。Enterprise の組織には、claude.ai と Claude Cowork を 通じてアップロードされたカスタムスキルに対するコンテンツスキャンが提供されている。ドキュメントは、Skills API や Console を 通じてアップロードされたスキルはその対象外であると注記している。エンジニアリング記事も独自の言葉で同じ助言をしており、 悪意のあるスキルは、それが使われる環境に脆弱性を持ち込んだり、データを流出させたり、意図しない行動をモデルに指示したり する可能性があると警告し、信頼性の低い情報源からのスキルは使用前に通読し、そのコードの依存関係、画像やスクリプトなどの 同梱リソース、そして信頼できない外部ネットワーク上の情報源に接続する指示に注意を払うよう求めている。どちらの記述も、 この形式自体が提供する仕組みではなく、手作業での監査を提案している。

証拠と限界

Google は、Gemini API 向けのスキル（Gemini API 開発者スキル）を構築し、117 のコード生成 プロンプトからなる評価ハーネスでそれを評価したと報告している。その結果、推論を強力にサポートする新しいモデルでは成績が 顕著に向上したが、古いモデルではその効果ははるかに小さかった。Google はこの結果を、スキルは機能するが、その効果は スキル単体ではなくモデルの推論能力に依存する、と読んでいる。手法と数値は Agent Skills で知識のギャップを埋める に記載されている。

上記のメルカリの記録は、ここにある情報源の中で、スキルが何を追加するかではなく、スキル自体の構造の評価を報告している 唯一のものである。その手法には注意が必要である。スコアは同じ著者が書いた評価用スキルから得られたもので、同じ著者が実際の 改善トピックから集めたデータセットに対して、同じ著者が実装前に定義した基準（理解の正確さ、仕様の具体性、実現可能性、 UX の妥当性）に照らして実行されている。記事は数値を示しておらず、改善を定量化するのではなく明確だったと述べるにとどまり、 短いファイルのほうがスコアが高かった理由については、その変数を分離した実験ではなく著者自身の推論を報告している。基準を 先に定義すること自体が 1 つの手法として提示されており、記事はそれを Prompt TDD と呼んでいる。

Anthropic 自身のエンジニアリング記事は、この形式の評価や測定を報告していない。スキルに同梱されるコンテキストは事実上 無制限であるという主張は、ファイルシステムを備えたエージェントが読む必要のないものについてのアーキテクチャ上の議論で あって、測定された結果ではない。また、この形式の利点についての説明は設計者自身によるものである。

Google の著者たちは 2 つの限界を挙げている。彼らは、Vercel の取り組みから、AGENTS.md による直接的な 指示のほうがスキルを使うよりも効果的な場合があることを知っていると述べ、そのためドキュメント用の MCP サーバーなど、 最新の SDK の知識を提供する他の経路を検討しているとしている。Vercel の評価そのものはこのウィキの情報源に含まれていない ため、ここに記録されているのは、Google の著者たちがそこから何を読み取ったと述べているかである。 2 つ目は保守である。Google は、ユーザーに手動での更新を求める以外に、スキルの更新についての良い方策がないと述べ、これは 長期的にはユーザーのワークスペースに古いスキル情報を残し、益よりも害をもたらしかねないと警告している。この懸念は、 ここでこの形式が使われている目的と相反する。エージェントを最新の状態に保つために導入された仕組みそれ自体が、その場で 古くなりうるからである。

Anthropic は、出荷済みの振る舞いではなく意図として 2 つの方向性を示している。外部ツールを伴うワークフローをエージェントに 教えることによって、スキルが Model Context Protocol サーバーをどう補完できるかを探ること、そして エージェントが自らスキルを作成、編集、評価できるようにすることである。

関連用語

• 段階的開示（Progressive Disclosure） — この形式の設計の中心にある読み込み戦略
• コンテキストエンジニアリング — この形式が取り組む、より広い関心事
• AGENTS.md — エージェントに常設の指示を与えるための、ファイルベースの別の慣例
• Claude Code — この形式が利用可能な製品の 1 つ
• OpenAI Codex — この形式をサポートしていると文書化されている別の製品
• 手続き的ギャップ — 研究文献が、スキルが橋渡しするものとして提示している不足
• エージェントスキルに関する包括的サーベイ：分類、技法、応用 — エージェントスキルの研究をライフサイクルに沿って整理したサーベイ