Agent Skillsとは？SKILL.mdとMCPの違い

エージェントスキルとは何か

エージェントスキルは、SKILL.md というファイルを含むディスク上のフォルダーです。このファイルには、名前、短い説明、プレーンな Markdown で記述した指示が含まれます。エージェントは起動時に説明を読み込み、リクエストがその説明に一致した場合、またはスキル名を指定して呼び出した場合にだけ指示を読みます。スキルに関するほぼすべての動作は、この2つの文から導けます。

フォルダーには、1つのファイル以外のものも格納できます。Agent Skills specification では、3つのオプションディレクトリを定義しています。scripts/ はエージェントが実行するコード用、references/ は必要に応じてエージェントが読むドキュメント用、assets/ はテンプレートとデータ用です。いずれも必須ではありません。SKILL.md だけを含むフォルダーでも、完全なスキルとして機能します。

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

説明は、過小評価されがちな部分です。エージェントがスキルを開くかどうか判断する前に確認できる唯一のテキストだからです。そのため、スキルの機能と使用する場面を、実際に人が入力する言葉で説明する必要があります。

スキルが使用するまでほとんどコストを消費しない理由

この仕組みを理解する価値を示す論点は、機能ではなくコンテキストにあります。読み込みは段階的に行われます。仕様ではこれを段階的開示と呼んでいます。

起動時にエージェントが読み込むのは、インストール済みの各スキルの name と description だけです。それ以外は読み込みません。Agent Skills specification の公開ガイダンス（2026 年 10 月時点）では、これはスキル 1 つあたり約 100 tokens とされています。スキルを 12 個インストールしても、消費するコンテキストは長い段落 1 つ分ほどです。

リクエストが説明に一致すると、エージェントはその SKILL.md の本文を読み込みます。仕様では、本文を 5,000 tokens 未満、ファイルを 500 行未満に保つことを推奨しています。この時点では、references/ と scripts/ のファイルはまだコストを消費しません。参照ファイルは、指示によってエージェントが参照した場合にだけ読み込まれます。バンドルされたスクリプトはさらに異なります。エージェントはスクリプトを shell 経由で実行するため、スクリプトのソースはコンテキストウィンドウに入りません。入るのはその出力だけです。

これを、最初に選ばれがちな巨大な prompt と比較してみます。system prompt や常時有効な instructions file の各行は、タスクに必要かどうかに関係なく、すべてのリクエストとすべてのセッションで消費されます。しかも、実際の質問と注意を奪い合います。常時適用する instructions が 10,000 tokens あると、時刻を尋ねるだけでもその分を支払うことになります。スキル 12 個の待機時コストは約 1,200 tokens で、必要なタスクに対してだけ増加します。これがスキルを使う理由のすべてです。長い prompt より小さなライブラリのほうが優れているのはそのためです。

ただし、注意点があります。スキルを読み込むと、その本文はセッションの残りの間コンテキストに保持されます。そのため、長い SKILL.md は 1 回限りではなく、繰り返し発生するコストになります。詳細を references/ に移すのは、単なる整理ではありません。これは仕組みが設計どおりに動作するための方法です。

エージェントのスキルはツール呼び出しではない

ツール、別名 function call は、モデルが呼び出せる機能です。ハーネスはモデルに、名前、説明、引数の形式を定義したスキーマを渡します。モデルが呼び出しを生成すると、コードがそれを実行し、結果がメッセージとして返されます。ツールは処理を実行します。このやり取りの両側を モデルの周囲でループを実行するプログラムであるハーネス が担います。起動時にスキルの説明を読み、スキルを読み込むタイミングを決めるのもハーネスです。

スキル自体は何も実行しません。エージェントがスキルを読み、すでに利用できるツールを使って処理します。モデルは、ツールに渡すような形でスキルに引数を渡すことはできません。スキルにできるのは、どのツールをどの順序で使い、その後に何を確認するかをモデルに指示することです。別のエージェントに作業を渡す場合が、最も分かりやすい例です。1 つの Claude Code セッションから、別のセッションにメッセージを送ることはすでにできます。その処理を行う価値がある条件と、送信する内容を記述する場所がスキルです。

要するに、ツールはエージェントに新しい能力を与え、スキルは主に、すでに持っている能力を使う際の判断基準を与えます。スキルが能力を追加する場合も、エージェントがすでに利用できる shell で実行する、同梱スクリプトを通じて行います。毎回、正確で検証済みの結果を生成する必要がある手順には、ツールまたはスクリプトを使います。同じ考え方を一貫して適用する必要がある手順には、スキルを使います。スキルは判断基準だけで構成されていても、最も頻繁に使うものになり得ます。その例が Ponytail です。これは coding agent に、動作する最小限の変更を行わせます。新しい能力は追加せず、エージェントがすでに持っている能力の使い方だけを変えます。この判断基準は逆方向にも働きます。unlazy skill は Depth Tree を使って、エージェントが作業を早い段階で完了と判断するのを防ぎます。これは、抑制ではなく徹底性を重視する同じ仕組みです。

エージェントスキルは MCP サーバーではない

MCP (model context protocol) は、エージェントを外部システムに接続するためのプロトコルです。MCP サーバーは、そのプロトコルで通信し、エージェントにツールを公開するプロセスです。通常は、設定、認証情報、ローカルコマンドまたはネットワークエンドポイントが必要です。スキルは、Markdown ファイルを含むフォルダーです。プロセスもポートもプロトコルもありません。

コンテキストのコストも同様に異なります。MCP サーバーが公開する各ツールには、名前、説明、引数スキーマがあります。これらを事前に読み込むクライアントでは、使用するかどうかに関係なく、セッション全体を通じてリクエストに含まれます。Claude Code は、デフォルトではこの方式を使用しなくなりました。2026 年 10 月時点では、ツール検索が標準で有効になっているため、セッション開始時に読み込まれるのはツール名とサーバーの指示だけです。完全な定義は、Claude が検索したときに読み込まれます。保存されたスキルは 1 行のテキストです。

この 2 つは補完関係にあり、最も強力な構成では両方を使用します。MCP サーバーはアクセス手段を提供します。スキルは手順を提供します。チームの実際のワークフローで、どのツールをどの順序で呼び出すか、そして適切な結果がどのようなものかを定義します。自分でホストする場合は、VPS で MCP サーバーを実行するでその側面を説明しています。

エージェントスキルはシステムプロンプトや AGENTS.md ではありません

どちらも Markdown 形式の指示であるため、混同しやすいのは当然です。違いは読み込まれるタイミングにあります。AGENTS.md、CLAUDE.md、およびシステムプロンプトは常に有効です。一方、スキルは要求に応じて呼び出されます。Claude Code の output styles は常に有効な設定の極致に位置しており、選択するとシステムプロンプト自体を書き換えます。そのため、スキルが一切関与しないやり取りを含め、セッション内のすべての回答に影響を与えます。

判断基準は「この段落の内容を無視することが、無関係なタスクにおいて誤りとなるか」という1点です。ハウススタイル、ビルドコマンド、ブランチ命名規則はあらゆるタスクに適用されるため、常に有効なファイルに記述すべきであり、毎回読み込まれることに意味があります。月に2回実行するリリースチェックリストはすべてのタスクに適用されるわけではないため、スキルに含めるべきです。常に有効なファイル内のセクションが番号付きの手順へと成長したなら、それが移行の合図です。

これらのファイルには、正しく扱うべき独自の慣習があります。AGENTS.md に含めるべき内容と人間用のファイルに含めるべき内容、および コードベースの構造を説明する design.md を参照し、私たちが採用している2つの慣習を確認してください。

最小限のスキルの構成

Claude Code では、個人用スキルを ~/.claude/skills/<name>/SKILL.md に配置すると、すべてのプロジェクトに適用されます。プロジェクト用スキルは .claude/skills/<name>/SKILL.md に配置して Git にコミットするため、そのリポジトリで作業するすべてのユーザーとエージェントが利用できます。GitHub Copilot と VS Code は、.github/skills/、.agents/skills/、.claude/skills/ からプロジェクト用スキルを読み込みます。これらに含まれるファイルは同一です。

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

これで完全なスキルになります。ディレクトリ名が入力するコマンドになるため、このスキルのコマンドは /restore-drill です。Claude Code では、/skills メニューにインストール済みのスキルが表示されます。ファイルが読み込まれたことを確認する最も簡単な方法です。メニューに表示されない場合は、まず名前を確認します。ファイル名は SKILL.md でなければなりません。また、Agent Skills 仕様では、名前に使用できるのは小文字、数字、単一のハイフンだけで、ディレクトリ名と一致している必要があります。同じ作業をエージェントが再実行できる手順として記述すると、VPS での restic の定期バックアップ と組み合わせて使えます。バックアップが実行されることと、バックアップから復元できることは同じではありません。

スキルではなくスクリプトにすべき場合

毎回同じ正解になる手順は、すべてスクリプトにします。スキルには、実行するタイミングと出力の読み方だけを数行で記述します。実用上の理由は2つあります。

1つ目は、スクリプトのソースコードがコンテキストウィンドウに入らないことです。300行のパーサーでも、必要になるのは出力だけです。同じ処理を Markdown の手順として記述すると、スキルを読み込むたびに全体が必要になります。

2つ目は、スクリプトが常に同じ結果を返すことです。同じログ解析ルールを毎回導き直すようモデルに指示すると、悪い場合には実行ごとに少しずつ結果が変わります。2つの数値が一致しなくなるまで、その違いに気付けないこともあります。

そのため、処理の種類ごとに分けます。「CSV を解析し、合計が明細項目と一致しない行をすべて出力する」はスクリプトです。「スクリプトが出力した行を確認し、データ入力ミスに見えるものを説明する」はスキルの指示です。判断を Markdown に残し、決定的な処理をコードに任せることは、エージェントが監視なしで実行できるループを構築するのと同じ方針です。

スキルがまったく起動しないのはなぜですか？

原因は、description にスキルの機能だけが書かれており、いつ使うかが書かれていないためです。エージェントがリクエストと照合できるのは、その 1 行だけです。「データベース作業を支援する」では、具体的な一致がありません。「staging データベースに対してスキーマ移行を実行する。ユーザーがテーブルの移行、列の追加、またはスキーマの変更を依頼した場合に使用する」と書けば、実際にユーザーが入力する語句が含まれるため、起動します。

反対に、常に起動してしまうスキルもあります。「このリポジトリでコードを変更するときは常に使用する」のような説明は、あらゆるタスクに一致します。そのため、本文が毎回読み込まれ、その後のセッション中ずっとコンテキストに残ります。意図したケースに限定して説明を書きます。Claude Code では、frontmatter に disable-model-invocation: true を設定することもできます。これにより自動読み込みを停止し、名前を入力したときだけスキルを使用できるようになります。

3 つ目の問題は、ツールと重複するスキルです。MCP サーバーがすでに公開している API をエージェントに curl するよう指示したり、harness に検索ツールがあるのにファイルを grep で検索するよう指示したりすると、処理が遅くなります。また、互いに矛盾する 2 組の指示が生じます。重複する指示を削除し、意図を記述します。

3 つのうちどれに該当するかを推測しないでください。新しいセッションを用意し、スキルを使用できる状態と無効にした状態で、同じプロンプトを 2 回実行して回答を比較します。新しいセッションを使うことが重要です。スキルを書いたセッションには、スキルの内容がすでにすべて含まれているため、記述内容の不足が隠れるからです。Anthropic の skill-creator plugin を使うと、Claude Code 内でこの比較を自動化できます。スキルが起動するはずのプロンプトと起動しないはずのプロンプトを生成し、それぞれの起動頻度も測定できます。スキルが読み込まれているのにエージェントが指示どおり動作しない場合、問題は説明ではありません。次は、すでに読み込んだ指示をエージェントが無視して別の応答をする理由を確認してください。

これは 1 社のベンダー独自形式ですか、それとも標準ですか？

Anthropic は 2025 年後半にこの形式を公開し、その後 agentskills.io でホストするオープン標準としてリリースしました。2026 年 10 月時点で、この仕様では必須の name と description フィールド、オプションの license、compatibility、metadata、allowed-tools フィールド、3 つのオプションディレクトリ、段階的な読み込み動作が定義されています。さらに、リファレンスバリデーターも提供されているため、skills-ref validate ./my-skill で共有前にフォルダーが仕様に準拠しているか確認できます。

実際の判断材料になるのは、対応クライアントの一覧です。同じフォルダーを Claude Code、Cursor、OpenAI Codex、Gemini CLI、GitHub Copilot、VS Code、Goose、OpenHands、opencode などが読み取ります。Microsoft は github.com/microsoft/skills で、この形式の独自スキルを公開しています。また、Skill Recorder というデスクトップツールも提供しています。このツールは、ユーザーがタスクを 1 回実行する様子を監視し、その内容を意図と順序付きの手順として再構成して、スキルとして書き出します。あるベンダーが、他社の仕様に属する形式で出力するレコーダーを開発していることは、その形式が 1 つの製品だけの機能ではなくなったことを示す有力な兆候です。

最初に書くもの

ライブラリを計画してはいけません。同じ指示をチャットに 3 回貼り付けていることに気付くまで待ち、そのテキストを SKILL.md に移して、貼り付けた内容を削除します。すでに自分で経験した繰り返しだけが、残す価値のあるスキルを作る確実なきっかけになります。検索手順は最初のスキルとして適しています。自分の SearXNG インスタンスを使った検索スキルが、その形を示しています。

ライブラリを健全に保つには、2 つの習慣が役立ちます。自分で作成していないスキルは、インストールする前に、スクリプトも含めてすべて読んでください。スキルはエージェントが従う指示であり、エージェントが実行する可能性のあるコードでもあるため、見知らぬ相手のソフトウェアをインストールする場合と同じように扱います。また、認証情報をフォルダーに置かないでください。スキルはコミットや共有の対象になるテキストファイルだからです。エージェントから Secret を遠ざける方法では、代わりにそれらの値を置く場所を説明しています。今年エージェントを学ぶためのロードマップでは、セットアップの他の要素とともに、スキルを学ぶ順序を示しています。

FAQ

エージェントスキルと MCP server の違いは何ですか？

MCP（model context protocol）server は、プロトコル経由でエージェントにツールを公開する実行中のプロセスです。そのため、設定と認証情報が必要です。また、クライアントが定義の読み込みを遅延させない限り、すべてのツール定義がセッション全体のコンテキストを占有します。Claude Code では現在、デフォルトで読み込みが遅延されます。エージェントスキルは SKILL.md ファイルを含むフォルダーです。プロセスもプロトコルもなく、エージェントが読むと判断するまでのコストは約 100 tokens です。エージェントにシステムへのアクセスを提供するには MCP server を使います。そのアクセスを適切に使う手順をエージェントに伝えるにはスキルを使います。両方を使う構成も一般的です。

エージェントスキルは Claude Code でしか使えませんか？

いいえ。Anthropic がこの形式を開発し、その後 agentskills.io でオープン標準として公開しました。同じフォルダーを Cursor、OpenAI Codex、Gemini CLI、GitHub Copilot、VS Code、Goose、OpenHands などのクライアントが読み取れます。違いは、各クライアントが参照する場所と、認識する追加の frontmatter フィールドです。Claude Code は ~/.claude/skills/ と .claude/skills/ を読み取ります。GitHub Copilot と VS Code は、リポジトリ内の .github/skills/、.claude/skills/、または .agents/skills/ を読み取ります。SKILL.md ファイル自体は変更せずにクライアント間で移動できます。

処理が遅くなる前に、いくつのスキルをインストールできますか？

制約になるのは個数ではなく、起動時の予算です。インストールした各スキルは、仕様で公開されている指針によると、名前と説明で約 100 tokens を追加します。そのため、30 個のスキルを使うと、どれも使用していない段階で約 3,000 tokens を消費します。最初に低下するのは速度ではなくマッチングです。説明が重複するスキルが多いと、モデルが適切なスキルを選びにくくなります。説明が重複しないように記述し、使わなくなったスキルは削除してください。

この指示はスキルと AGENTS.md のどちらに置くべきですか？

リポジトリ内のすべてのタスクに適用されるかどうかで判断します。ビルドコマンド、組織内のスタイル、命名規則はすべてのタスクに適用されるため、常時読み込むファイルに置きます。毎回読み込むことが目的だからです。リリースチェックリストやリストア手順など、必要なときだけ実行する手順はスキルにします。不要なタスクでは、1 行の説明だけで済むためです。番号付きの手順に成長した AGENTS.md のセクションは、通常、移動すべきスキルです。