mcp-to-skill

MCP-to-Skill Converter

将 MCP 服务转换为按需加载的技能。每轮对话中，MCP 工具架构都会出现在系统提示词里（每个工具约占 500-2000 个令牌，无论是否使用）。技能在通过 view 加载前不消耗任何令牌。对于一个典型配置（4-5 个 MCP 服务，提供 20-40 个工具），每轮对话可因此释放 10,000-30,000 个上下文令牌。

这很重要，因为在对话开始前，上下文窗口就有 10-30% 被占用，而且这种开销会不断累积：每轮对话都会重新注入完整架构。

决策框架：转换还是保留

并非所有 MCP 都适合转换为技能。请遵循以下经验法则：

适合转换的情况：MCP 封装了 REST API（使用 curl/web_fetch）、封装了 CLI 工具（gh、aws、gcloud——直接调用）、实现了推理/规划模式（将其整理为方法论），或者你经常使用的工具不到其工具总数的一半。

适合保留为 MCP 的情况：它维护服务端持久状态（数据库连接、WebSocket 会话）、处理二进制协议或流式传输、提供实时事件订阅，或者规模很小（1-2 个工具、低于 500 个令牌——开销可以忽略不计）。

混合方式——将无状态工具转换为技能，把有状态工具保留为精简版 MCP。对于大型 MCP 服务，这通常是最佳选择。

---

转换工作流

分 5 个阶段进行。在每个阶段结束时展示发现结果，并等待用户确认后再继续。用户比任何分析都更了解自己的使用模式——请充分采纳他们的意见。

阶段 1：发现

获取 MCP 的工具定义。按以下顺序尝试这些来源：

1. 当前会话中的工具——检查当前对话中可见的工具。 请用户指出哪些工具属于目标 MCP。这是最可靠的来源，因为你能看到实际占用上下文的确切架构。

2. MCP 配置文件——解析用户的 MCP 配置：

   • Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor：项目根目录中的 .cursor/mcp.json
   • Claude Code：~/.claude/settings.json 或项目中的 .mcp.json
   • 配置文件提供服务名称和连接详情，不包含工具架构。

3. MCP 服务源代码——如果用户提供了仓库或本地路径，请查找工具定义：FastMCP @mcp.tool() 装饰器、SDK server.setRequestHandler 或类似模式。提取名称、描述、参数架构和返回类型。

4. 软件包注册表——对于已发布的 MCP：运行 npm info <pkg> 或 pip show <pkg>，然后获取 README 或源代码以查找工具定义。

5. 用户提供的架构——请用户粘贴或上传工具定义。

为每个工具生成结构化清单：

Tool: tool_name
Description: what it does
Parameters: param list with types
Returns: return type/shape
Estimated tokens: rough schema size

展示清单并询问：“这些就是全部工具吗？有没有遗漏？”

阶段 2：分类

从两个维度对每个工具进行分类。此分类将决定整个替换策略，因此务必准确。

替换类别：

类别	特征	替换方式
REST_API	HTTP 端点、URL 模式、认证标头	curl 或 web_fetch
CLI_WRAPPER	封装已知 CLI（git、gh、aws、docker）	直接调用 CLI
LOGIC_PATTERN	组织推理，无外部调用	SKILL.md 中的方法论
FILE_OP	读取／写入／转换本地文件	bash 命令或 Python
STATEFUL	维护连接、会话、缓存	保留为 MCP（标记出来）
COMPOSITE	编排多个子操作	多步骤工作流

使用频率 — 直接询问用户：

频率	操作
ESSENTIAL	必须包含在生成的技能中
NICE_TO_HAVE	只有替换方式简洁明了时才包含
RARELY_USED	跳过——用户可改为手动调用

展示分类表并询问：“看起来合理吗？你平时实际会用哪些工具？”

明确标记所有 STATEFUL 工具——这些工具可能无法顺利转换，用户应该了解其中的取舍。

阶段 3：替换策略

为每个标记为 ESSENTIAL 或 NICE_TO_HAVE 的工具设计具体替换方案。

阅读 references/replacement-patterns.md——其中包含各类别的详细模式：REST API 封装、CLI 映射、逻辑模式、文件操作、有状态工具的变通方案、组合工作流、认证模式和输出解析。

对于每个工具，确定：

• 替换它的确切命令（curl、CLI 或方法论）
• MCP 工具参数如何映射到命令参数
• 如何将输出解析为实用格式
• 常见错误情形及其修复方法

同时找出多工具工作流——用户经常串联使用的工具序列。这些将成为生成技能中的“常见工作流”部分，也是技能往往比 MCP 更有价值之处，因为工作流会明确呈现多步骤模式，而不是依赖 Agent 自行发现。

询问用户：

• “你的环境中有哪些 CLI 工具可用？”
• “你是否经常按特定顺序组合使用多个工具？”
• “你如何处理认证？”（环境变量、配置文件、OAuth 令牌）

如果目标环境不明确，阅读 references/environment-guide.md，了解特定环境的限制（Claude.ai、Claude Code、Cursor 与 API）。

阶段 4：生成

生成完整的技能包。

阅读 references/skill-template.md，了解输出模板、篇幅指南、frontmatter 检查清单和质量检查清单。

生成的技能结构：

skill-name/
  SKILL.md
    Frontmatter (name, description with aggressive triggers)
    Quick Reference table (old tool name to new command mapping)
    Prerequisites (CLI tools, env vars, auth setup)
    Core Operations (one subsection per essential tool)
    Common Workflows (multi-step patterns)
    Error Handling and Troubleshooting
  references/                        (only if SKILL.md exceeds ~400 lines)
    api-reference.md                 (overflow for complex tool replacements)

生成规则——这些规则旨在确保生成的技能在实际使用中确实会被触发并正常工作：

• Frontmatter 描述必须有明确的触发引导。 将原始 MCP 工具名称作为触发短语，并包含服务名称、动作动词，以及明确的“在……时使用此技能”措辞。技能默认不易被触发，因此应尽量扩大覆盖范围。
• 顶部放置快速参考表。 用户和 Agent 会先浏览这里。
• 每项核心操作都应说明它替代的内容、替换命令、参数映射、具体示例和错误处理。
• 将 SKILL.md 控制在 500 行以内。 如有需要，将详细模式移至 references/。
• 通过环境变量或配置文件进行认证，绝不可硬编码。 生成的技能不得嵌入凭据。
• 先决条件应包含每个必需 CLI 工具的安装命令。

阶段 5：验证

生成后，验证技能并估算节省量。

使用 scripts/estimate_tokens.py 估算 token 数：

python3 scripts/estimate_tokens.py --mcp-tools TOOL_COUNT --avg-schema-chars AVG_CHARS

这会显示每轮对话以及典型对话中的前后 token 节省量。

**Opus 4.7 说明：**由于分词器更新，相同文本的输入 token 数是 Opus 4.6 的 1.0–1.35 倍。请将 4.7 之前的基线视为下限——Opus 4.7 上的实际节省量可能高于估算器报告的数值。

生成 2–3 个测试场景——编写能触发新技能的真实提示词，并展示替代命令的实际效果。将这些场景呈现给用户。

迁移清单：

• 已审查生成的技能并应用所需修改
• 已安装所需的 CLI 工具并完成身份验证
• 已将技能放置在目标技能目录中
• 已从配置中移除 MCP
• 已验证测试场景

验证生成的技能结构：

确认生成的技能目录中包含格式有效的 SKILL.md 文件，且带有 frontmatter（name、description），并且正文中的所有文件引用都能解析到技能目录中的现有文件。

向用户呈现完整的交付包。提出可针对任何部分继续迭代。

---

局限性

无状态工具和 REST/CLI 封装的转换效果最佳。固有限制如下：

• 有状态工具无法顺利转换——维护持久连接、会话或实时订阅的 MCP 应保留为 MCP。请参阅决策框架中的“适合保留为 MCP 的情况”。
• 二进制协议和流式传输——如果 MCP 处理二进制数据或 WebSocket 流，则转换需要 Claude 范围之外的额外基础设施。
• 虚构 API 的风险——只有在已知底层 API 或 CLI 的情况下，替代方案才可行。必须先研究未知 API；猜测会导致技能无法正常工作。
• 身份验证复杂性——涉及多步骤 OAuth 或凭据管理的转换是可行的，但需要明确设置环境变量和配置。身份验证模式请参阅阶段 3。
• 接受部分覆盖——保留一个有状态 MCP、完成 90% 的转换，优于尝试 100% 转换却导致失败。应如实说明权衡。

---

约束

这些约束旨在防止生成技能时常见的失败情况：

• 绝不虚构 API 端点。 如果底层 API 未知，请询问用户或研究 MCP 的源代码。猜测 URL 会导致技能无法正常工作。
• 如实说明局限性。 转换 80% 的工具并保留一个小型 MCP，比生成声称覆盖全部功能却无法正常工作的技能更好。
• 呈现前先在头脑中测试。 逐一检查每条替代命令：它是否真的能运行？curl 是否需要特定请求头？CLI 工具是否需要身份验证设置？
• 保留错误处理质量。 许多 MCP 会提供实用的错误消息。生成的技能应包含相应的故障排查指南。