エージェントスキルとは？MCPとの違いも解説

エージェントスキルの実体

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

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

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

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

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

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

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

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

これを、多くの人が最初に選ぶ方法である巨大なプロンプトと比較してください。system prompt や常時有効な指示ファイルの各行は、タスクに必要かどうかにかかわらず、すべてのリクエストとすべてのセッションで消費されます。さらに、実際の質問と注意を奪い合います。常時有効な指示が 10,000 トークンあれば、時刻を尋ねるだけでもその分を支払うことになります。スキルを 12 個使う場合、待機時のコストは約 1,200 トークンで、必要なタスクに対してだけ増加します。これがスキルを使う根拠のすべてであり、長いプロンプトより小さなライブラリが優れている理由です。

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

エージェントのスキルはツール呼び出しではありません

ツール（function call とも呼ばれます）は、モデルが呼び出せるものです。ハーネスは、名前、説明、引数の形式を含むスキーマをモデルに渡します。モデルが呼び出しを生成すると、コードがツールを実行し、その結果がメッセージとして返されます。ツールは処理を実行します。

スキルは単独では何も実行しません。エージェントがスキルを読み、すでに利用できるツールを使って処理します。モデルは、ツールに引数を渡す場合と同じ方法でスキルに引数を渡すことはできません。スキルができるのは、どのツールをどの順序で使い、その後に何を確認するかをモデルに指示することです。

要点は、ツールがエージェントに新しい能力を与えるのに対し、スキルは、すでに持っている能力をどう使うかの判断基準を与えるということです。毎回、正確で検証済みの結果を生成する必要がある手順には、ツールまたはスクリプトが適しています。同じ思考を一貫して適用する必要がある手順には、スキルが適しています。

エージェントスキルは MCP サーバーではありません

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

コンテキストの消費量も同様に異なります。MCP サーバーが公開する各ツールには、名前、説明、引数スキーマがあります。これらは、使用するかどうかにかかわらず、デフォルトではセッション全体のリクエストに含まれます。一部のクライアントでは、ツールスキーマを必要に応じて取得するようになっていますが、最初に読み込む方式が依然として一般的です。保存された状態のスキルは、1 行のテキストです。

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

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

どちらも Markdown の指示なので、この混同は無理もありません。AGENTS.md、CLAUDE.md、システムプロンプトは常に有効です。スキルは必要なときだけ有効になります。

判定基準は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/ のワークスペーススキルを読み込みます。中に置くファイルは同じです。

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 でなければならず、ディレクトリ名には小文字、数字、単独のハイフンだけを使用します。エージェントが再実行できる手順として同じ作業を記述すると、VPS でスケジュール実行する restic バックアップ のような運用と自然に組み合わせられます。バックアップが実行されていることと、バックアップから復元できることは同じではありません。

スキルではなくスクリプトにすべき処理

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

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

2つ目は、スクリプトなら同じ入力に対して毎回同じ結果になることです。同じログ解析ルールを実行のたびにモデルが再導出すると、調子が悪いときには結果が少し変わります。2つの数値が一致しなくなるまで、その違いに気付けないこともあります。

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

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

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

逆に、常に起動してしまうスキルもあります。「このリポジトリでコードを変更する場合に使用する」のような説明は何にでも一致するため、すべてのタスクで本文が読み込まれ、その後のセッション中もコンテキストに残ります。想定したケースに合うよう、説明を限定してください。Claude Code では frontmatter に disable-model-invocation: true を設定することもできます。これにより自動読み込みを停止し、名前を入力した場合にスキルを使用できる状態を維持します。

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

この3つのどれに該当するかを推測しないでください。新しいセッションを開始し、スキルを使用可能にした状態と無効にした状態で、同じプロンプトを2回実行してから回答を比較します。新しいセッションが重要なのは、スキルを作成したセッションにはスキルの内容がすでにすべて含まれており、記述したスキルの不足が見えなくなるためです。Anthropic の skill-creator plugin は Claude Code 内でこの比較を自動化します。スキルが起動すべきプロンプトと起動すべきでないプロンプトの生成や、それぞれの起動頻度の測定にも対応しています。

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

Anthropic は 2025 年後半にこの形式を公開し、その後 agentskills.io でホストするオープン標準としてリリースしました。2026 年 8 月時点で、この仕様では必須の 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 サーバーの違いは何ですか？

MCP（model context protocol）サーバーは、プロトコルを介してエージェントにツールを公開する実行中のプロセスです。そのため、設定と認証情報が必要です。また、ツール定義は通常、使用するかどうかにかかわらずセッション全体のコンテキストを占有します。エージェントスキルは、SKILL.md ファイルを含むフォルダーです。プロセスもプロトコルもなく、エージェントが読み込むと判断するまでのコストは約 100 トークンです。エージェントからシステムへのアクセスを提供するには MCP サーバーを使用します。そのアクセスを適切に使用する手順をエージェントに伝えるにはスキルを使用します。多くの構成では、両方を使用します。

エージェントスキルは 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/ を読み込みます。SKILL.md ファイル自体は変更せずにクライアント間で移動できます。

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

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

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

リポジトリ内のすべてのタスクに適用されるかどうかを確認してください。ビルドコマンド、チーム内のスタイル、命名規則はすべてのタスクに適用されるため、常に読み込むファイルに記述します。毎回読み込むことが目的だからです。リリースチェックリストやリストア手順など、時々実行する手順はスキルにします。必要のないタスクではコストが発生しないためです。AGENTS.md のセクションが番号付きの手順に発展している場合、それは通常、移動すべきスキルです。