bolasblack MCP Skill Generator
Convert MCP servers into Claude Code skills with progressive disclosure pattern.
Before You Start
Read https://code.claude.com/docs/en/skills for the latest skill best practices.
Workflow
1. Get MCP Server Info
Ask user for: documentation URL, package name, or direct connection info (stdio command or HTTP URL).
2. Version Locking (When Possible)
Version locking prevents supply chain attacks, but only applies when the MCP server supports it:
| Server Type | Can Lock? |
|---|---|
| Package (npm, pip, cargo, etc.) | ✅ Yes - use package manager's version syntax |
| Remote HTTP service | ⚠️ Maybe - only if API supports versioning |
| Local binary/service | ❌ No |
If lockable, record the version in config.toml (version and versionLockedAt fields).
If package but not lockable, STOP and warn user loudly:
⚠️ SECURITY WARNING
Cannot lock version for this package. The package maintainer could push malicious updates at any time.
Do you trust the publisher of
<package-name>?Only proceed if you fully trust them. Type "yes I trust" to continue.
If remote service, no extra warning needed - user implicitly trusts it by choosing to convert.
3. Extract Schema
Run from this skill's directory (use subshell to preserve pwd):
(cd /path/to/mcp-skill-generator && node ./scripts/schema-extractor.mjs --stdio "npx <package>@<version> <args>")
# or
(cd /path/to/mcp-skill-generator && node ./scripts/schema-extractor.mjs --http "<url>")
4. Generate Skill
Create directory structure:
~/.claude/skills/mcp-[server-name]/
├── SKILL.md # Overview (use templates/SKILL.md.template)
├── tools/ # One file per tool (use templates/tool.md.template)
├── config.toml # Connection config (see docs/config-format.md)
├── resources.md # Resource docs (if server has resources)
├── prompts.md # Prompt docs (if server has prompts)
└── scripts/
├── mcp-transport.mjs # Transport layer
├── mcp-caller.mjs # CLI interface
└── api.mjs # Programmatic API for batch/parallel calls
5. Ask Save Location
- Project:
.claude/skills/mcp-[name]/ - Personal:
~/.claude/skills/mcp-[name]/
6. Copy Scripts
mkdir -p <target>/scripts
cp -f /path/to/mcp-skill-generator/scripts/mcp-transport.mjs <target>/scripts/
cp -f /path/to/mcp-skill-generator/scripts/mcp-caller.mjs <target>/scripts/
cp -f /path/to/mcp-skill-generator/scripts/api.mjs <target>/scripts/
Only copy these 3 runtime files. Do NOT copy files not needed at runtime (e.g., schema-extractor.mjs).
7. Show Summary
Display: tools/resources/prompts count, save location, locked version, usage instructions.
Updating Existing Skills
- Read existing config.toml
- Check for newer version:
npm view <package> version - Extract fresh schema
- Compare changes: "3 new tools, 1 removed, 2 modified"
- Regenerate files (preserve user customizations)
- Always overwrite scripts/
Reference
- Design document - Architecture, design decisions, and trade-offs
- config.toml format - Configuration examples and environment variables
- templates/ - SKILL.md and tool.md templates
Release history
See CHANGELOG.md for release history. VERSION is the skill version owner; server versions in connection configs are separate.