/mcp-to-skill

name: mcp-to-skill
description: 'Converts MCP servers into on-demand skills to cut context window usage, classifying each tool by replacement strategy and generating the skill package. Triggers on: "convert MCP", "MCP to skill", "reduce context size", "too many tools", "tool token bloat", "MCP migration".'
metadata:
  version: 1.1.1
  category: data
  tags: [mcp, skill-conversion, context-optimization, token-reduction]
  difficulty: intermediate
  phase: build

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:**

| Category | Signals | Replacement Approach | | --------------- | ------------------------------------------ | ----------------------- | | `REST_API` | HTTP endpoints, URL patterns, auth headers | curl or web_fetch | | `CLI_WRAPPER` | Wraps known CLI (git, gh, aws, docker) | Direct CLI invocation | | `LOGIC_PATTERN` | Structures reasoning, no external calls | Methodology in SKILL.md | | `FILE_OP` | Reads/writes/transforms local files | bash commands or Python | | `STATEFUL` | Maintains connections, sessions, caches | Keep as MCP (flag it) | | `COMPOSITE` | Orchestrates multiple sub-operations | Multi-step workflow |

**Usage frequency** — Ask the user directly:

| Frequency | Action | | -------------- | ---------------------------------------------- | | `ESSENTIAL` | Must be in the generated skill | | `NICE_TO_HAVE` | Include if the replacement is clean | | `RARELY_USED` | Skip — user can fall back to manual invocation |

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 hand