エージェントスキルとは？仕組みと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 仕様では、これはスキル1つあたりおよそ100 tokens とされています（2026年8月時点の公開ガイダンス）。スキルを12個インストールしても、消費するコンテキストは長い段落1つ分ほどです。

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

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

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

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

ツール（function call とも呼ばれます）は、モデルが呼び出せる機能です。harness はモデルに、名前、説明、引数の形式を定義した schema を送ります。モデルが呼び出しを生成すると、コードがそれを実行し、結果がメッセージとして返されます。ツールは処理を実行します。

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

要点は次のとおりです。ツールはエージェントに新しい能力を与え、skill はエージェントがすでに持っている能力を使うための判断基準を与えます。毎回、正確で検証済みの結果を生成する必要がある手順には、ツールまたはスクリプトが適しています。同じ考え方を一貫して適用する必要がある手順には、skill が適しています。最小限の変更で動作させるよう coding agent を促す Ponytail の例が示すように、skill は判断基準だけで構成されていても構いません。新しい能力は追加せず、エージェントがすでに持っている能力の使い方だけを変える skill が、最も頻繁に使うものになる場合もあります。

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

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

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

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

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

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

判断基準は1つです。その段落と無関係なタスクで、その段落を無視すると問題になるでしょうか。ハウススタイル、ビルドコマンド、ブランチ命名規則はすべてのタスクに適用されるため、常に読み込まれることが重要な常時適用ファイルに記載します。月に2回実行するリリースチェックリストはすべてのタスクに適用されるわけではないため、スキルに記載します。常時適用ファイルの一部が番号付きの手順に成長したら、移動する合図です。

これらのファイルにも、正しく設定すべき固有の規約があります。使用している2つのファイルについては、AGENTS.md に記載する内容と人間向けファイルに記載する内容 と コードベースの構成を説明する design.md を参照してください。

最小限のスキルの構成

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 バックアップのよい補助になります。バックアップが実行されることと、バックアップから復元できることは同じではありません。

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

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

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

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

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

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

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

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

3つ目の失敗は、ツールと同じ機能をスキルが重複して提供するケースです。MCP server がすでに公開している API をエージェントに curl するよう指示したり、harness に検索ツールがあるのにファイルを grep で検索させたりすると、処理が遅くなります。さらに、互いに矛盾する2組の指示が生じます。重複部分を削除し、意図を説明してください。

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

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

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 というデスクトップツールも提供しています。このツールは、タスクを一度実行する様子を監視し、タスクを意図と順序付きの手順として再構成し、その結果をスキルとして書き出します。あるベンダーが、別のベンダーの仕様に属する形式で出力するレコーダーを開発していることは、その形式が単一製品の機能ではなくなったことを示す有力な兆候です。

最初に書くもの

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

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

FAQ

agent skill と MCP server の違いは何ですか？

MCP (model context protocol) server は、プロトコル経由で agent にツールを公開する実行中のプロセスです。そのため、設定と認証情報が必要です。また、ツール定義は通常、使用するかどうかに関係なくセッション全体でコンテキストを占有します。agent skill は SKILL.md ファイルを含むフォルダーです。プロセスもプロトコルもなく、agent が読むと判断するまでのコストは約 100 tokens です。agent からシステムへアクセスできるようにするには MCP server を使います。そのアクセスを適切に使う手順を agent に伝えるには skill を使います。両方を実行する構成もよく使われます。

agent skill は 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 ファイル自体は変更せずに各クライアント間で移動できます。

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

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

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

リポジトリ内のすべてのタスクに適用されるかどうかを考えてください。ビルドコマンド、プロジェクト固有のスタイル、命名規則はすべてのタスクに適用されるため、常時読み込むファイルに記述します。毎回読み込むことが目的だからです。リリースチェックリストやリストア手順など、たまに実行する手順は skill にします。そうすれば、その手順が不要なタスクではコストが発生しません。AGENTS.md のセクションが番号付きの手順に成長した場合は、通常、skill に移すべき状態です。