mcp-to-skill

Converts an MCP server into a zero-dependency skill package so AI agents can invoke tools directly via Bash commands, without launching an MCP process or injecting all tool definitions upfront.

Step 1: Get MCP information

Determine the input type:

A — User provided a command string / local path / URL: Confirm the command is available, proceed to Step 2.

B — User pasted tool schema JSON: Save the JSON to a temp file, skip Step 2, go directly to Step 3. Use the Write tool to save the pasted JSON to /tmp/mcp-schema-input.json. In Step 3, use --schema-json /tmp/mcp-schema-input.json.

C — User hasn't specified, wants to pick from registered MCPs: List the MCPs currently registered with the agent and let the user choose. In Claude Code: run claude mcp list

Language preference: If the user specifies a language for the generated skill (e.g. "generate in Chinese", "用中文生成"), note it and apply it to all generated files in Step 5. Default is English.

Step 2: Run mcp_inspector.py (only for input type A or C)

Locate mcp_inspector.py: it is in the same directory as this SKILL.md. Determine the absolute path of that directory from the path information provided by the agent framework when loading this skill, then run:

# Ensure mcp SDK is installed
pip show mcp > /dev/null 2>&1 || pip install mcp

python /path/to/skill-dir/mcp_inspector.py "<MCP command>" --output /tmp/mcp-inspector-output.json

Example output:

✓ Written to /tmp/mcp-inspector-output.json: 12 tools, source: /tmp/mcp-to-skill-cache/server-github

Use the Read tool to read /tmp/mcp-inspector-output.json and extract: server_name, source_path (may be null), tools[].

Step 3: AI analysis — infer equivalent commands

Read the inspector output (or the schema file from Step 1B).

If source_path is not null: Use Read / Grep tools to read the source files, locate the implementation for each tool, and extract:

• HTTP endpoint (URL, method, headers, body structure)
• or CLI invocation pattern

If source_path is null: Infer reasonable equivalent commands based solely on each tool's description and inputSchema.

Write a command draft for each tool with a confidence marker:

• [VERIFIED] — confirmed by source code (only when source is available)
• [INFERRED] — AI-inferred, logically sound but untested (max level when source_path is null)
• [TODO] — cannot be auto-generated, leave a placeholder with explanation

Step 4: Test read-only commands

For each [INFERRED] command that is a read-only operation (GET request, query), execute it with the Bash tool:

• Pass → upgrade to [VERIFIED]
• Fail → keep [INFERRED], add a comment above the command noting the failure reason
• Write operations (POST/PUT/DELETE, file modifications) — skip testing, keep [INFERRED]
• [TODO] items — do not test

Step 5: Generate skill package

Create the skill directory in the user's current working directory (or a user-specified path):

<mcp-server-name>/
  SKILL.md
  config.json            # public config (safe to commit)
  secrets.json           # secrets (gitignored, never commit)
  secrets.json.example   # secrets template (safe to commit)
  .gitignore
  helpers/               (create on demand, do not pre-create empty)
    tools-extended.md    (when tool count > 8)
    <tool>.py / <tool>.sh  (when logic cannot fit in a single command)

Progressive disclosure rules:

• tool count ≤ 8: write all tools into the SKILL.md quick-reference section
• tool count > 8: SKILL.md lists only the 8 most common tools; the rest go into helpers/tools-extended.md; add a note at the bottom of SKILL.md: "More tools: see helpers/tools-extended.md"

SKILL.md frontmatter template:

---
name: <server-name>
description: |
  [When to use]: <summarize usage scenarios from tool descriptions>
  [Does]: <core capabilities>
  [Does NOT]: <explicitly excluded scenarios>
  [Requires]: <runtime dependencies; write "no runtime dependencies" if none>
---

Config file separation (secret safety):

config.json — public config only, safe to commit:

{
  "endpoint": "<base URL extracted from source, or leave as placeholder>"
}

secrets.json — secrets only, must be gitignored:

{
  "auth_token": "<actual token>"
}

secrets.json.example — secrets template, safe to commit, for onboarding:

{
  "auth_token": "your-api-token-here"
}

.gitignore — contents:

secrets.json

Read order for scripts: secrets.json → environment variable (e.g. X_API_TOKEN). If both are empty, error and prompt user to copy the example file and fill it in.

Important: config.json and secrets.json are read on every tool call (not cached at startup).

Language: Generate all text content in the language specified in Step 1. Default is English.

If skill-creator is loaded in the agent context: Pass the analysis results (tool list + inferred commands + confidence markers) to skill-creator to generate SKILL.md.

Step 6: Register skill with the current AI agent

Goal: register the generated skill directory so it is immediately available. Probe in order and use the first that works:

1. Check if npx skills is available:

   which npx && npx skills --version 2>/dev/null
   

   If available: npx skills add <skill-path> -g -y

2. Check if running in Claude Code:

   claude --version 2>/dev/null
   

   If available: symlink to ~/.claude/skills/<skill-name>:

   ln -sf <skill-path> ~/.claude/skills/<skill-name>
   

   Note: /add-dir is an interactive slash command and cannot be called via Bash.

3. If neither applies: output the skill path and tell the user how to register manually:

   "Skill generated at <path>. Please register it with your AI agent. Claude Code users: run /add-dir <path> npx skills users: run npx skills add <path> -g"

Step 7: Ask about removing the original MCP (optional)

Only prompt when Step 1 was type A or C (not pasted schema):

"MCP <server-name> has been converted to a skill. Would you like to remove the MCP configuration from your AI agent?"

• User confirms → assist with removal (agent decides how)
• User declines or no response → skip, skill and MCP can coexist