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 INLINECODE2

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:

CODEBLOCK0

Example output:
CODEBLOCK1

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)
• INLINECODE11 — AI-inferred, logically sound but untested (max level when source_path is null)
• INLINECODE12 — 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 INLINECODE14
• Fail → keep [INFERRED], add a comment above the command noting the failure reason
• Write operations (POST/PUT/DELETE, file modifications) — skip testing, keep INLINECODE16
• INLINECODE17 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):

CODEBLOCK2

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:

CODEBLOCK3

Config file separation (secret safety):

INLINECODE19 — public config only, safe to commit:
CODEBLOCK4

INLINECODE20 — secrets only, must be gitignored:
CODEBLOCK5

INLINECODE21 — secrets template, safe to commit, for onboarding:
CODEBLOCK6

INLINECODE22 — contents:
CODEBLOCK7

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. 1. Check if npx skills is available:

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

1. 2. Check if running in Claude Code:

   claude --version 2>/dev/null
   

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

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

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