mcp-to-skill

MCP からスキルへの変換

MCP サーバーを、必要なときに呼び出すスキルに変換します。MCP ツールのスキーマは、使用するかどうかにかかわらず、毎ターン、システムプロンプトに含まれます（ツールごとに約 500～2000 トークン）。スキルは view で読み込むまでトークンを消費しません。一般的な構成では、20～40 個のツールを公開する 4～5 個の MCP サーバーを利用すると、ターンごとに 10,000～30,000 トークンのコンテキストを取り戻せます。

これは、会話が始まる前にコンテキストウィンドウの 10～30％が消費されることを意味します。さらに、毎ターン、スキーマ全体が再び挿入されるため、その影響は積み重なります。

判断の枠組み：変換するか、維持するか

すべての MCP をスキルにする必要はありません。次の目安を適用してください。

変換する場合：MCP が REST API をラップしている（curl／web_fetch を使う）、CLI ツール（gh、aws、gcloud など）をラップしている（直接実行する）、推論や計画のパターンを実装している（手法としてまとめる）、または定期的に使用するツールが半数未満の場合。

MCP として維持する場合：サーバー側の永続的な状態（DB 接続、WebSocket セッション）を管理する、バイナリプロトコルやストリーミングを処理する、リアルタイムのイベントサブスクリプションを提供する、または規模が小さい（ツールが 1～2 個で 500 トークン未満のため、オーバーヘッドが無視できる）場合。

ハイブリッド方式 — ステートレスなツールはスキルに変換し、ステートフルなツールは簡素化した MCP として維持します。大規模な MCP サーバーでは、この方法が最適なことがよくあります。

---

変換ワークフロー

5 つのフェーズに沿って進めます。各フェーズの区切りで調査結果を提示し、続行する前にユーザーの確認を待ちます。ユーザーは使用状況を最もよく把握しているため、分析で推測するよりも、ユーザーからの情報を重視してください。

フェーズ 1：調査

MCP のツール定義を取得します。次の情報源を上から順に確認してください。

1. アクティブなセッションのツール — 現在の会話で確認できるツールを調べます。どのツールが対象の MCP に属するか、ユーザーに確認してください。コンテキストを消費している正確なスキーマを確認できるため、これが最も信頼できる情報源です。

2. MCP 設定ファイル — ユーザーの MCP 設定を解析します。

   • Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor：プロジェクトルートの .cursor/mcp.json
   • Claude Code：~/.claude/settings.json またはプロジェクトの .mcp.json
   • 設定ファイルで確認できるのはサーバー名と接続情報であり、ツールのスキーマではありません。

3. MCP サーバーのソースコード — ユーザーがリポジトリまたはローカルパスを指定した場合は、ツール定義を探します。FastMCP の @mcp.tool() デコレーター、SDK の server.setRequestHandler、または類似のパターンを確認します。名前、説明、パラメータースキーマ、戻り値の型を抽出してください。

4. パッケージレジストリ — 公開されている MCP の場合は、npm info <pkg> または pip show <pkg> を実行し、その後 README またはソースを取得してツール定義を確認します。

5. ユーザー提供のスキーマ — ツール定義を貼り付けるか、アップロードするようユーザーに依頼します。

各ツールについて、次の項目を含む構造化された一覧を作成します。

Tool: tool_name
Description: what it does
Parameters: param list with types
Returns: return type/shape
Estimated tokens: rough schema size

これを提示して、次のように質問します：「これですべてのツールですか？見落としたものはありますか？」

フェーズ 2：分類

各ツールを 2 つの観点から分類します。この分類が置き換え戦略全体の基盤となるため、正しく分類することが重要です。

置き換えカテゴリ：

カテゴリ	判断の手がかり	置き換え方法
REST_API	HTTP エンドポイント、URL パターン、認証ヘッダー	curl または web_fetch
CLI_WRAPPER	既知の CLI（git、gh、aws、docker）をラップしている	CLI を直接呼び出す
LOGIC_PATTERN	推論を構造化し、外部呼び出しを行わない	SKILL.md の方法論
FILE_OP	ローカルファイルの読み取り／書き込み／変換を行う	bash コマンドまたは Python
STATEFUL	接続、セッション、キャッシュを維持する	MCP のまま維持（要注意）
COMPOSITE	複数のサブ操作を統合する	複数ステップのワークフロー

使用頻度 — ユーザーに直接尋ねます：

頻度	対応
ESSENTIAL	生成するスキルに必ず含める
NICE_TO_HAVE	置き換えがすっきりできる場合に含める
RARELY_USED	省略する — ユーザーは手動での呼び出しに切り替えられる

分類表を提示して、次のように尋ねます：「この内容でよさそうですか？ 実際に定期的に使用するツールはどれですか？」

STATEFUL ツールには明示的に印を付けます。これらは問題なく置き換えられない可能性があるため、ユーザーがトレードオフを理解できるようにします。

フェーズ 3：置き換え戦略

ESSENTIAL または NICE_TO_HAVE と分類された各ツールについて、具体的な置き換え方法を設計します。

references/replacement-patterns.md を読みます — 各カテゴリの詳細なパターンが記載されています。REST API ラッパー、CLI の対応付け、ロジックパターン、ファイル操作、ステートフルな場合の回避策、複合ワークフロー、認証パターン、出力の解析方法が含まれています。

各ツールについて、次の点を判断します：

• 置き換えに使う正確なコマンド（curl、CLI、または方法論）
• MCP ツールのパラメーターをコマンドの引数にどう対応付けるか
• 出力をどのように解析して、役立つ形式にするか
• よくあるエラーとその解決方法

また、複数ツールを使うワークフローも特定します。これは、生成するスキルの「一般的なワークフロー」セクションになります。ワークフローでは複数ステップのパターンが明示され、エージェントが自力で見つける必要がなくなるため、スキルが MCP より役立つこともよくあります。

ユーザーに次のように尋ねます：

• 「お使いの環境で利用できる CLI ツールは何ですか？」
• 「複数のツールを組み合わせて使う、よくある手順はありますか？」
• 「認証には何を使用していますか？」（環境変数、設定ファイル、OAuth トークンなど）

対象環境が不明な場合は、references/environment-guide.md を読みます。Claude.ai、Claude Code、Cursor、API それぞれの環境固有の制約が記載されています。

フェーズ 4：生成

スキルパッケージ全体を生成します。

出力テンプレート、サイズのガイド、フロントマターのチェックリスト、品質チェックリストについては、references/skill-template.md を読みます。

生成するスキルの構成：

skill-name/
  SKILL.md
    Frontmatter (name, description with aggressive triggers)
    Quick Reference table (old tool name to new command mapping)
    Prerequisites (CLI tools, env vars, auth setup)
    Core Operations (one subsection per essential tool)
    Common Workflows (multi-step patterns)
    Error Handling and Troubleshooting
  references/                        (only if SKILL.md exceeds ~400 lines)
    api-reference.md                 (overflow for complex tool replacements)

生成ルール — 生成されたスキルが実際に適切に起動し、正しく動作するようにするためのルールです。

• フロントマターの説明は、積極的な表現にします。 元の MCP ツール名をトリガーフレーズとして含め、サービス名、動作を表す動詞、「このスキルは次のような場合に使用します」という明示的な文言を含めます。スキルはデフォルトでは起動されにくいため、幅広く該当するようにします。
• 先頭にクイックリファレンス表を置きます。 ユーザーとエージェントは最初にここを確認します。
• 各コア操作には、置き換える対象、置き換えコマンド、パラメーターの対応付け、具体例、エラー処理を示します。
• SKILL.md は 500 行未満にします。 必要に応じて、詳細なパターンを references/ に移します。
• 認証情報は環境変数または設定ファイルから取得し、ハードコードはしません。 生成するスキルに認証情報を埋め込んではいけません。
• 前提条件には、必要な CLI ツールすべてのインストールコマンドを含めます。

フェーズ 5：検証

生成後、スキルを検証し、削減量を見積もります。

scripts/estimate_tokens.py を使用してトークン数を推定します：

python3 scripts/estimate_tokens.py --mcp-tools TOOL_COUNT --avg-schema-chars AVG_CHARS

これにより、1ターンあたり、および一般的な会話全体での変更前後のトークン削減量が表示されます。

Opus 4.7 に関する注意： トークナイザーの更新により、同じテキストでも入力トークン数は Opus 4.6 の 1.0～1.35 倍になります。Opus 4.7 より前のベースラインは下限として扱ってください。Opus 4.7 での実際の削減量は、推定値より大きくなる場合があります。

テストシナリオを 2～3 件作成します。新しいスキルを呼び出す現実的なプロンプトを用意し、置き換え後のコマンドが動作する様子を示します。ユーザーに提示してください。

移行チェックリスト：

• 生成されたスキルを確認し、必要な編集を適用済み
• 必須の CLI ツールをインストールし、認証済み
• スキルを対象のスキルディレクトリに配置済み
• MCP を設定から削除済み
• テストシナリオを検証済み

生成されたスキルの構造を検証します：

生成されたスキルディレクトリに、フロントマター（name、description）を含む有効な SKILL.md があること、および本文内のすべてのファイル参照がスキルディレクトリ内の既存ファイルを指していることを確認します。

パッケージ全体をユーザーに提示します。各セクションを調整できることも伝えてください。

---

制限事項

ステートレスなツールや REST／CLI ラッパーでは、最も適切に変換できます。以下のような固有の制約があります。

• ステートフルなツールは適切に変換できません — 永続的な接続、セッション、またはリアルタイムのサブスクリプションを維持する MCP は、MCP のままにしてください。「Decision Framework」の「Keep as MCP when」を参照してください。
• バイナリプロトコルとストリーミング — MCP がバイナリデータや WebSocket ストリームを処理する場合、変換には Claude の範囲外の追加インフラストラクチャが必要です。
• API を捏造するリスク — 置き換えの方法が機能するのは、基盤となる API または CLI が判明している場合のみです。不明な API は、まず調査する必要があります。推測すると、スキルが機能しなくなります。
• 認証の複雑さ — 複数段階の OAuth や認証情報の管理を伴う変換も可能ですが、環境変数と設定を明示的にセットアップする必要があります。認証のパターンについては、フェーズ 3 を参照してください。
• 部分的な対応でも問題ありません — ステートフルな MCP を 1 つ残して 90% を変換するほうが、100% を目指して失敗するより望ましいです。トレードオフについては正直に伝えてください。

---

制約事項

生成されるスキルでよくある失敗を防ぐため、以下の制約を設けています。

• API エンドポイントを決して捏造しないでください。 基盤となる API が不明な場合は、ユーザーに尋ねるか、MCP のソースコードを調査してください。URL を推測すると、スキルが機能しなくなります。
• 制限事項について正直に伝えてください。 すべてに対応できると主張しながら機能しないスキルを作るより、残りの小さな MCP を 1 つ残してツールの 80% を変換するほうが望ましいです。
• 提示する前に頭の中でテストしてください。 置き換え後のコマンドを一つずつ確認してください。実際に動作するでしょうか？ curl に特定のヘッダーが必要でしょうか？ CLI ツールには認証のセットアップが必要でしょうか？
• エラー処理の品質を維持してください。 多くの MCP は役立つエラーメッセージを提供します。生成されたスキルにも、それと同等のトラブルシューティング手順を含めてください。