mcp-to-skill-converter — Summary

A single-file Python script (mcp_to_skill.py) that converts any MCP server configuration into a Claude Code skill package implementing the "progressive disclosure" pattern. The core claim: traditional MCP server loading puts all tool definitions into context at startup (20 tools ≈ 30k tokens always loaded), while a generated skill loads only ~100 tokens of metadata at startup, ~5k tokens when the skill fires, and 0 tokens for tool execution.

The converter introspects the MCP server to get its tool list, generates a SKILL.md with instructions for Claude, an executor.py that handles MCP protocol communication at runtime, and supporting config files. The generated skill directs Claude to identify the appropriate tool, generate a JSON call specification, and invoke the executor script — effectively converting the MCP tool-call paradigm into a subprocess invocation paradigm.

This is a single-developer proof-of-concept (GBSOSS on GitHub) with 3 files and no version history beyond the initial commit. It's explicitly inspired by the "playwright-skill" progressive disclosure pattern. Compared to seeds: closest to ccmemory (MCP-anchored toolserver) but inverts the relationship — rather than building an MCP server that replaces skills, it builds skills that wrap MCP servers. The mcp2skill framework (fenwei-dev, also in this batch) is a more polished Go implementation of the same concept.

mcp-to-skill-converter — Overview

Origin

Created by GBSOSS (GitHub), exact date unknown (repo has minimal commit history). A direct response to the MCP context window problem, explicitly citing playwright-skill as the inspiration for the "progressive disclosure" pattern.

Philosophy

"MCP servers are great but load all tool definitions into context at startup. With 20+ tools, that's 30-50k tokens gone before Claude does any work."

The solution philosophy: wrap MCP servers in skills that load lazily. The key architectural insight is the three-tier disclosure model:

• Startup: ~100 tokens (just metadata — skill name and description)
• When used: ~5k tokens (full instructions and tool list loaded into context)
• Executing: 0 tokens (executor.py runs the MCP call externally, output only)

Token Savings Example (from README)

Before (MCP):
  20 tools = 30k tokens always loaded
  Context available: 170k / 200k = 85%

After (Skills):
  20 skills = 2k tokens metadata
  When 1 skill active: 7k tokens
  Context available: 193k / 200k = 96.5%

GitHub MCP Server Example

Scope

3 files: README.md, mcp_to_skill.py (generator), example-github-mcp.json (example config). Single author, proof-of-concept quality. The MCP introspection in the current code is marked as a "mock response for demonstration" — the actual MCP server connection is not fully implemented.

mcp-to-skill-converter — Architecture

Distribution

standalone-repo — a single Python script with no packaging.

Install

# 1. Create MCP config file (example-github-mcp.json)
# 2. Run converter
python mcp_to_skill.py \
  --mcp-config github-mcp.json \
  --output-dir ./skills/github
# 3. Install generated skill dependency
cd skills/github && pip install mcp
# 4. Copy to Claude Code skills directory
cp -r . ~/.claude/skills/github

Generated Skill Structure

skills/<name>/
├── SKILL.md        # Claude instructions (generated)
├── executor.py     # MCP communication handler (generated)
├── mcp-config.json # MCP server connection config (copied)
└── package.json    # Python dependency declaration (generated)

Conversion Pipeline

Input: MCP server config JSON (command + args + env)
  ↓
MCPSkillGenerator._get_mcp_tools()   # introspect MCP server
  ↓ (currently returns mock data — NOT fully implemented)
MCPSkillGenerator._generate_skill_md()   # generate SKILL.md
MCPSkillGenerator._generate_executor()   # generate executor.py
MCPSkillGenerator._generate_config()     # copy mcp-config.json
MCPSkillGenerator._generate_package_json()
Output: Skill directory

Runtime Execution (generated executor.py)

Claude Code loads SKILL.md (~5k tokens)
  → Claude identifies tool + generates JSON call spec
  → Claude runs: python executor.py --call '{"tool": "...", "arguments": {...}}'
    → executor.py connects to MCP server via stdio
    → sends tools/call request
    → reads response
    → prints to stdout
  → Claude reads stdout output

Dependencies

• Python with asyncio
• mcp Python package (for generated executor.py)

Target AI Tools

• Claude Code (skill discovery)
• Any agent that supports skills in the same format

Limitations

The _get_mcp_tools() method is a stub returning mock data. A production use requires replacing this with actual MCP tools/list protocol exchange. The mcp2skill tool in this batch (fenwei-dev) is a working Go implementation of the same concept.

mcp-to-skill-converter — Components

Scripts (1)

Classes (in mcp_to_skill.py)

Generated Output (per MCP server)

Commands (0)

No CLI commands shipped. Single invocation: python mcp_to_skill.py --mcp-config <file> --output-dir <dir>

CLI Arguments

Skills (0 native, N generated)

The converter itself ships no skills. It generates skills from MCP configs.

Hooks (0)

None.

MCP Servers (0 bundled)

None bundled. The converter reads third-party MCP configs.

Templates (1)

The mcp_to_skill.py script contains embedded template strings for:

• SKILL.md content template (with tool list, context savings table, usage pattern)
• executor.py content template
• package.json content template

Example Input Config

{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {"GITHUB_TOKEN": "your-token-here"}
}

mcp-to-skill-converter — Uniqueness

differs_from_seeds

None of the 11 seeds address MCP-to-skill conversion. ccmemory (Archetype 3 seed) is the conceptual inverse — it builds an MCP server that replaces Claude Code's native memory skills. This converter inverts that: it wraps any MCP server in a skill abstraction to get progressive disclosure. taskmaster-ai is the closest in architecture (single MCP server with many tools exposed as named primitives), but taskmaster-ai ships its own MCP server while this tool converts third-party servers.

Positioning

Proof-of-concept that has a more complete Go successor in the same batch (mcp2skill by fenwei-dev). The Python version is simpler, more readable, and more hackable; the Go version has a proper CLI with OAuth support and update detection.

Distinctive Opinion

The README makes a strong claim: "90% context savings" by converting from MCP to skills. The token math is plausible but depends heavily on the MCP server being converted. Servers with many large schemas save more; servers with few simple tools save less.

Critical Limitation

The _get_mcp_tools() method is stubbed with mock data:

# In a real implementation, this would:
# 1. Start the MCP server process
# 2. Send tools/list request
# 3. Parse the response

# Mock response for demonstration
return [{"name": "example_tool", ...}]

This means the converter does not actually introspect real MCP servers as of the analyzed commit. The generated executor.py does implement real MCP protocol calls, but the SKILL.md generation uses mock tool data.

Observable Failure Modes

1. Mock introspection: SKILL.md generated from fake tool data, not real server
2. No connection pooling: Each tool call spawns a fresh MCP server process — expensive for servers with slow startup
3. No streaming: Blocking executor incompatible with long-running tools
4. Python dependency: executor.py requires pip install mcp — not always available in skill context
5. Path hardcoding risk: $SKILL_DIR substitution must be done by Claude — if Claude gets the path wrong, all executor calls fail

Relationship to mcp2skill

Both this converter and mcp2skill (fenwei-dev) implement the same MCP-to-skill conversion concept. mcp2skill is the production-quality Go binary with proper OAuth, update detection, and actual MCP introspection. This Python script is the proof-of-concept prototype.