首页 › skills-review › 教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 的“路由器”，原文如下：

---
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：

<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 与第一道铁律

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 的核心是一棵画在代码块里的决策树：

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，用法原文：

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 提炼的写法模式

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

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

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

四、安装与使用

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

# 在 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 拉起来。

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 作者）：并列第一。一个教你管上下文，一个教你管流程。

参考来源

anthropics/skills 仓库首页 — 仓库结构（/skills、/spec、/template）、文档与示例 Skill 分类、插件安装命令
mcp-builder/SKILL.md — frontmatter 原文、四阶段流程、参考文档加载时序、评测输出格式
mcp-builder/reference/ 目录 — 确认 evaluation.md、mcp_best_practices.md、python/node_mcp_server.md 四个参考文件
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学通信知识星球海报-扫码加入