<!-- title: 教Claude造MCP：官方Skill逐段拆解 -->

# 教 Claude 造 MCP Server：官方 mcp-builder + webapp-testing 逐段拆解

## 概述

本期做单点深拆，对象是官方仓库 anthropics/skills 里最“工程师向”的一对 Skill：**mcp-builder**（教 Claude 从零造一个 MCP 服务器）和 **webapp-testing**（教 Claude 用 Playwright 验收本地 Web 应用）。把它们放一起拆是因为二者天然构成一条流水线——前者负责“造工具”，后者负责“验工具”。更重要的原因是：这两份 SKILL.md 是目前公开可读的、把「渐进式加载」「上下文保护」「强制验收环节」三个设计思想贯彻得最彻底的范本，逐段看完，你自己写 Skill 的品味会上一个台阶。

## 评测对比表

| 维度 | 权重 | mcp-builder | webapp-testing |
|------|------|-------------|----------------|
| 功能完整度 | 25% | ★★★★★ | ★★★★ |
| 设计质量 | 25% | ★★★★★ | ★★★★★ |
| 实战效果 | 20% | ★★★★ | ★★★★ |
| 上手难度 | 15% | ★★★★ | ★★★★☆ |
| 社区活跃度 | 15% | ★★★★★（官方仓库直出） | ★★★★★（官方仓库直出） |
| **加权印象** | — | **4.8** | **4.6** |

说明：二者都随官方仓库分发，不存在第三方 Skill 常见的“弃坑”风险；社区活跃度直接锚定 anthropics/skills 本身。截至发稿抓取该 GitHub 页面显示约 173k stars、20.5k forks（此数字来自单次页面抓取，未经第二来源交叉验证，仅供参考）。

## 一、mcp-builder：一份“四阶段施工图”

### 1.1 先看 frontmatter：触发词是怎么写的

SKILL.md 开头的 YAML 是整个 Skill 的“路由器”，原文如下：

```yaml
---
name: mcp-builder

description: Guide for creating high-quality MCP (Model Context Protocol)
  servers that enable LLMs to interact with external services through
  well-designed tools. Use when building MCP servers to integrate external
  APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

license: Complete terms in LICENSE.txt
---
```

注意 description 的两句式结构：**前半句定义“是什么”，后半句用 "Use when..." 明确触发时机**。这不是装饰——Claude 判断是否激活一个 Skill，几乎完全依赖这段 description。"Use when building MCP servers to integrate external APIs or services" 精确圈定了触发场景，还顺手把双语言支持（Python/FastMCP 和 Node/TypeScript SDK）写进了触发条件，等于告诉模型：“只要用户提 MCP + 任意一种语言，都归我管”。想写自己 Skill 的读者，先把这两句式抄下来。

另外 `license: Complete terms in LICENSE.txt` 这个写法延续了官方文档类 Skill 的惯例：正文开源可读，但授权条款单独放在 LICENSE.txt 里，目录里也确实有这个文件。

### 1.2 正文骨架：四阶段，编号到小数点

正文标题是 "MCP Server Development Guide"，骨架为：

- **Overview** → **Process**（一张 🚀 High-Level Workflow 总览）
- **Phase 1: Deep Research and Planning**（1.1 理解现代 MCP 设计 / 1.2 读 MCP 协议文档 / 1.3 读框架文档 / 1.4 规划实现）
- **Phase 2: Implementation**（2.1 搭项目结构 / 2.2 实现核心基础设施 / 2.3 实现 Tools）
- **Phase 3: Review and Test**（3.1 代码质量 / 3.2 Build 并用 MCP Inspector 测试）
- **Phase 4: Create Evaluations**（4.1 理解评测目的 / 4.2 出 10 道评测题 / 4.3 评测要求 / 4.4 输出格式）

编号精确到 `2.3` 这种粒度，是官方 Skill 的典型手法：**把长任务切成有明确“完成标志”的小步**，模型每完成一小步就有确认点，不容易在长流程里迷路或跳步。

### 1.3 最值得抄的设计：按阶段门控的参考文档加载

SKILL.md 末尾有一节 "📚 Documentation Library"，它的子标题本身就是一份加载时序表：

- Core MCP Documentation **(Load First)**
- SDK Documentation **(Load During Phase 1/2)**
- Language-Specific Implementation Guides **(Load During Phase 2)**
- Evaluation Guide **(Load During Phase 4)**

对应的实体文件在 `skills/mcp-builder/reference/` 下，一共四个：`mcp_best_practices.md`、`python_mcp_server.md`、`node_mcp_server.md`、`evaluation.md`，另有 `scripts/` 目录放配套脚本。

这就是 Agent Skills 规范里“渐进式披露”（progressive disclosure）的标准落地：**SKILL.md 本体永远不塞实现细节，细节拆进 reference/，并在正文里写明“哪一步才允许读哪个文件”**。造一个 MCP Server 可能涉及几万字协议文档，如果全部塞进 SKILL.md，Skill 一激活上下文就爆炸；门控加载后，Phase 4 之前模型根本不会碰 evaluation.md。

### 1.4 Phase 4 是灵魂：强制 Claude 给自己出考卷

大多数“生成器”类 Skill 生成完就结束，mcp-builder 例外——它要求 Phase 4 产出一个评测文件：**恰好 10 道复杂、真实的测试题**，且每道题必须满足六个约束：independent（相互独立）、read-only（只读，不改数据）、complex、realistic、verifiable（答案可验证）、stable（答案不随时间漂移）。输出格式是 XML：

```xml
<qa_pairs>
  <qa_pair>
    <question>...</question>
    <answer>...</answer>
  </qa_pair>
</qa_pairs>
```

这六个约束是精心挑的：read-only 保证评测不污染真实数据，stable 保证评测可以反复回归。“强制验收环节”是这份 SKILL.md 和市面上大量“模板生成器” Skill 拉开差距的地方——它不假设 Claude 造出来的东西能用，而是要求给出可复核的证据。

### 1.5 散落在正文里的提示词工程细节

几个值得单独点名的段落：

- **工具命名**：要求统一前缀，如 `github_create_issue`、`github_list_repos`，让 LLM 在工具列表里靠前缀聚类。
- **四种注解**：实现 tool 时必须标 `readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`——这些是 MCP 协议的 hint 注解，直接决定调用方（也就是未来的 Claude）敢不敢放心调这个工具。
- **上下文管理**：明确要求工具返回“聚焦、相关的数据”，避免一次调用灌回海量 JSON。
- **报错信息**：要求 actionable，报错必须带具体建议，而不是甩一个 stack trace。
- **技术选型**：直接给结论——TypeScript 优先，远程服务器用 Streamable HTTP（无状态 JSON），本地用 stdio。好的 Skill 应该替用户做掉这类选型题，mcp-builder 做了。

## 二、webapp-testing：一份“防呆手册”

### 2.1 frontmatter 与第一道铁律

```yaml
name: webapp-testing
description: Toolkit for interacting with and testing local web applications
  using Playwright. Supports verifying frontend functionality, debugging UI
  behavior, capturing browser screenshots, and viewing browser logs.
license: Complete terms in LICENSE.txt
```

正文开篇第一段就立了一条规矩，原文：

> **Important:** Always run scripts with `--help` first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is absolutely necessary. These scripts can be very large and thus pollute your context window.

这是我近期读过的所有 SKILL.md 里最聪明的一段话。它针对的正是 Agent 的真实恶习：**遇到 `scripts/with_server.py` 这种大脚本，模型的第一反应是把源码整个读进上下文**，一次 Read 就可能吃掉几万 token，还容易在细节里迷失。这条铁律的解法是“把脚本当黑盒”：先跑 `--help` 看用法，直接调用，实在不行才许读源码。写自己 Skill 时，只要你的 Skill 带脚本，就值得原样抄这条。

### 2.2 用 ASCII 决策树代替长篇说明

SKILL.md 的核心是一棵画在代码块里的决策树：

```text
User task → Is it static HTML?
    ├─ Yes → Read HTML file directly to identify selectors
    │         ├─ Success → Write Playwright script using selectors
    │         └─ Fails/Incomplete → Treat as dynamic (below)
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Run: python scripts/with_server.py --help
        └─ Yes → Reconnaissance-then-action: ...
```

静态页面和动态应用走完全不同的路径，服务器起没起又分两条路。**用决策树而不是段落，是给模型看的流程图**——分支条件、每条分支的第一个动作都一目了然，模型几乎不可能走错岔路。这比一堆 "if... then..." 的自然语言省 token 且更不易误读。

### 2.3 with_server.py：一个脚本解决“服务器生命周期”问题

测试本地应用最烦的是起服务、等端口、测完关服务。这个 Skill 只提供一个 helper，用法原文：

```bash
python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
```

还支持多服务器（backend + frontend 各一条 `--server`）。注意设计取舍：**它不封装“测试”本身，只封装“环境准备”**。测试逻辑仍由 Claude 现场写 Playwright 脚本完成。这个边界划得很好——环境管理是重复劳动，适合做成脚本；页面结构千变万化，封装成工具反而僵化。

### 2.4 侦察-行动模式与那个著名的坑

对动态页面，SKILL.md 规定了固定套路 "Reconnaissance-then-Action"：先导航并等 `networkidle` → 截图或读 DOM → 从渲染结果里找 selector → 再执行操作。配套还有一个用 ❌/✅ 标出的 "Common Pitfall"：**不许在等待 `networkidle` 之前去 inspect DOM**——这是 Playwright 自动化最高频的翻车点（JS 还没执行完，元素根本不存在），Skill 把它上升为明文禁令。示例代码里甚至在内联注释里写死 `# Always launch chromium in headless mode`，防呆防到了行级。

### 2.5 examples/ 目录

`examples/` 下给了三个可直接模仿的样例：`element_discovery.py`（发现页面上的按钮/链接/输入框）、`static_html_automation.py`（用 file:// URL 测本地 HTML）、`console_logging.py`（抓浏览器 console 日志）。**给三个覆盖典型场景的最小样例，而不是一个大而全的 demo**，这个配比值得所有 Skill 作者参考。

## 三、从这两份 SKILL.md 提炼的写法模式

把上面的拆解压缩成五条可直接复用的模式：

1. **两句式 description**：一句定义能力，一句 "Use when..." 圈定触发时机。
2. **阶段门控加载**：细节进 reference/，正文标注“哪阶段读哪个文件”，别让 Skill 一激活就撑爆上下文。
3. **脚本黑盒铁律**：明文禁止一上来读脚本源码，先 `--help` 再调用。
4. **决策树 > 段落**：分支逻辑画成 ASCII 树，每条分支只写第一个动作。
5. **强制验收**：生成类 Skill 必须自带“出考卷/跑测试”环节，用可复核的证据收尾，而不是一句“完成了”。

其中 mcp-builder 是模式 2、5 的范本，webapp-testing 是模式 3、4 的范本。

## 四、安装与使用

来自官方 README 的插件方式（两条 marketplace 命令为原文）：

```bash
# 在 Claude Code 中添加官方 marketplace
/plugin marketplace add anthropics/skills

# 安装示例技能包（mcp-builder、webapp-testing 所在系列）
/plugin install example-skills@anthropic-agent-skills

# 文档技能包（docx/pdf/pptx/xlsx）
/plugin install document-skills@anthropic-agent-skills
```

或手动方式：克隆 `anthropics/skills`，把 `skills/mcp-builder`、`skills/webapp-testing` 整个文件夹拷到 `~/.claude/skills/`（项目级则放 `.claude/skills/`）。

触发方式零配置：装好后在 Claude Code 里直接说“帮我给 XX API 写一个 MCP Server”或“测试一下这个本地页面能不能正常提交表单”，description 里的 "Use when..." 就会把对应 Skill 拉起来。

```mermaid
flowchart TD
    A[用户: 给 XX API 造个 MCP Server] --> B[mcp-builder 激活]
    B --> P1[Phase 1 研究规划]
    P1 -.Load First.-> R1[mcp_best_practices.md]
    P1 --> P2[Phase 2 实现 Tools]
    P2 -.Phase 2 加载.-> R2[python_mcp_server.md<br/>node_mcp_server.md]
    P2 --> P3[Phase 3 Build + MCP Inspector]
    P3 --> P4[Phase 4 出 10 道 eval 题]
    P4 -.Phase 4 加载.-> R3[evaluation.md]
    P4 --> T{产物是 Web 应用?}
    T -->|是| W[webapp-testing 激活]
    T -->|否| D[交付 MCP Server + 评测文件]
    W --> W1[--help 先行<br/>禁止读脚本源码]
    W1 --> W2{页面类型?}
    W2 -->|静态 HTML| W3[直接读 HTML 找 selector]
    W2 -->|动态应用| W4[with_server.py 起服务<br/>networkidle 后侦察 DOM]
    W3 --> W5[写 Playwright 脚本执行验证]
    W4 --> W5
    W5 --> D
```

## 五、适用与不适用场景

**mcp-builder 适合**：为有 REST/SDK 的外部服务造 MCP 接入层；想把内部系统暴露给 Claude 用。**不适合**：只想调现成 MCP 的用户（那是配置问题，不需要造）；对 MCP 协议零概念的新手——它默认你懂 tool/schema，上手难度四星由此而来。

**webapp-testing 适合**：本地 dev server 的功能验收、UI 回归、截图取证、console 报错排查。**不适合**：生产环境监控（它明确面向 local web applications）、非 Web 的桌面应用。另外它依赖本机装有 Python + Playwright，环境缺失时第一步就会卡住。

## 六、推荐排行榜

- **提示词工程质量榜**：webapp-testing（`--help` 铁律 + 决策树）＞ mcp-builder（阶段门控）
- **流程完备度榜**：mcp-builder（四阶段 + 强制 eval）＞ webapp-testing
- **上手成本榜（越低越好）**：webapp-testing ＞ mcp-builder（后者要求 MCP 概念前置）
- **可抄性榜（给 Skill 作者）**：并列第一。一个教你管上下文，一个教你管流程。

## 参考来源

1. [anthropics/skills 仓库首页](https://github.com/anthropics/skills) — 仓库结构（/skills、/spec、/template）、文档与示例 Skill 分类、插件安装命令
2. [mcp-builder/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/mcp-builder/SKILL.md) — frontmatter 原文、四阶段流程、参考文档加载时序、评测输出格式
3. [mcp-builder/reference/ 目录](https://github.com/anthropics/skills/tree/main/skills/mcp-builder/reference) — 确认 evaluation.md、mcp_best_practices.md、python/node_mcp_server.md 四个参考文件
4. [webapp-testing/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md) — `--help` 铁律、决策树、with_server.py 用法、侦察-行动模式原文

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)