MCP To Skill

MCP-to-Skill Converter

Convert MCP servers into on-demand skills. MCP tool schemas sit in the system prompt on every turn (~500-2000 tokens per tool, regardless of whether they're used). Skills cost zero tokens until loaded via view. For a typical setup with 4-5 MCP servers exposing 20-40 tools, this reclaims 10,000-30,000 tokens of context per turn.

This matters because that's 10-30% of the context window burned before the conversation even starts — and it compounds: every turn re-injects the full schema.

Decision Framework: Convert vs. Keep

Not every MCP should become a skill. Apply this heuristic:

Convert when the MCP wraps a REST API (use curl/web_fetch), wraps a CLI tool (gh, aws, gcloud — invoke directly), implements a reasoning/planning pattern (capture as methodology), or when you use fewer than half its tools regularly.

Keep as MCP when it maintains persistent server-side state (DB connections, WebSocket sessions), handles binary protocols or streaming, provides real-time event subscriptions, or is tiny (1-2 tools, under 500 tokens — negligible overhead).

Hybrid approach — convert the stateless tools to a skill, keep stateful ones as a slimmed-down MCP. This is often the sweet spot for large MCP servers.

Conversion Workflow

Proceed through 5 phases. Present findings at each phase boundary and wait for user confirmation before continuing. The user knows their usage patterns better than any analysis can infer — lean on their input.

Phase 1: Discovery

Acquire the MCP's tool definitions. Try these sources in order:

1. Active session tools — Inspect tools visible in the current conversation. Ask the user to identify which tools belong to the target MCP. This is the most reliable source because you see the exact schema consuming context.

2. MCP config file — Parse the user's MCP configuration:

   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor: .cursor/mcp.json in the project root
   • Claude Code: ~/.claude/settings.json or project .mcp.json
   • Config files give server names and connection details, not tool schemas.

3. MCP server source code — If the user points to a repo or local path, look for tool definitions: FastMCP @mcp.tool() decorators, SDK server.setRequestHandler, or similar patterns. Extract name, description, parameter schemas, return types.

4. Package registry — For published MCPs: npm info <pkg> or pip show <pkg>, then fetch the README or source to find tool definitions.

5. User-provided schema — Ask the user to paste or upload tool definitions.

Produce a structured inventory for each tool:

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

Present this and ask: "Are these all the tools? Did I miss any?"

Phase 2: Classification

Classify each tool along two dimensions. This classification drives the entire replacement strategy, so getting it right matters.

Replacement category:

Usage frequency — Ask the user directly:

Present a classification table and ask: "Does this look right? Which tools do you actually use regularly?"

Flag any STATEFUL tools explicitly — these are the ones that may not convert cleanly, and the user should understand the trade-off.

Phase 3: Replacement Strategy

For each tool marked ESSENTIAL or NICE_TO_HAVE, design the concrete replacement.

Read references/replacement-patterns.md — it contains detailed patterns for each category: REST API wrappers, CLI mappings, logic patterns, file operations, stateful workarounds, composite workflows, auth patterns, and output parsing.

For each tool, determine:

• The exact command (curl, CLI, or methodology) that replaces it
• How MCP tool parameters map to command arguments
• How to parse the output into a useful format
• Common error cases and their fixes

Also identify multi-tool workflows — sequences of tools the user commonly chains. These become "Common Workflows" sections in the generated skill, which is where skills often provide more value than the MCP because workflows make the multi-step pattern explicit rather than relying on the agent to discover it.

Ask the user:

• "What CLI tools are available in your environment?"
• "Are there common sequences where you use multiple tools together?"
• "How do you handle authentication?" (env vars, config files, OAuth tokens)

If the target environment is unclear, read references/environment-guide.md for environment-specific constraints (Claude.ai vs Claude Code vs Cursor vs API).