拆webapp-testing：让Claude自己考自己

概述

这是本栏 Skills 生态观察的第 2 轮单件深拆。前几期拆过 superpowers、mcp-builder、官方 docx/pdf 家族、Humanizer 等明星件，本期选了一个栏目历史上从未拆过的新面孔：webapp-testing——Anthropic 官方 example-skills 插件家族里的「网页自测件」。它的任务只有一句话：让 Claude 写完网页之后，自己打开浏览器把它测了。但真正值得拆的不是功能，而是它的写法：全文不到一百行的 SKILL.md，把「上下文经济学」刻进了每一行——它会明确禁止 Claude 去读自己的脚本源码，理由是“会污染你的上下文窗口”。本期逐段拆它的 SKILL.md，对照同门两件（doc-coauthoring、canvas-design）讲清官方示例的三种设计物种，最后给出六条可以直接抄去写你自己第一个 Skill 的心法。本文全部引文来自本机安装的插件原文，未采信二手转述。

一、为什么是它

翻遍本栏 150 条选题史：官方件拆过 docx、pdf、xlsx、skill-creator、theme-factory、web-artifacts-builder、frontend-design（审美件），社区件拆过 superpowers、Humanizer、planning-with-files——但 webapp-testing 一直没人动过。它是官方 example-skills 家族里最「工具型」的一件：不谈审美、不谈流程仪式感，通篇都在解决一个硬问题——Agent 写完的网页，怎么在没有测试工程师坐旁边的情况下完成验收。

更有意思的是它的物种属性。把官方 example-skills 插件里的三份 SKILL.md 原文摆在一起看，会发现同一棵树上结出了三种完全不同的果子：

三种物种对应三类任务：工具型适合「有明确成败的动作」，流程型适合「多轮协作的长会话」，审类型适合「主观但有毒.Tx 隙的产出」。webapp-testing 是工具型的官方样板，这就是本期拆它的理由。

三物种分家谱系：

flowchart TD
    R["官方示例插件三件"]
    R --> A["工具型 webapp-testing"]
    R --> B["流程型 doc-coauthoring"]
    R --> C["审类型 canvas-design"]
    A --> A1["脚本当黑盒跑"]
    A --> A2["决策树派活"]
    B --> B1["三阶段状态机"]
    B --> B2["新开Claude当读者"]
    C --> C1["宣言式审美催眠"]
    C --> C2["零脚本纯约束"]

二、评测对比表

评分基于本栏对三份 SKILL.md 原文的通读比对，1–5 星；「上手难度」5 星代表最省心。社区活跃度一项，因三件同属官方插件捆绑分发、外部实时热度数据本次未能联网核验，改按发行渠道计分并如实标注。

一个耐人寻味的结论：本轮深拆的主角总分只排第二。doc-coauthoring 靠零依赖、张口就赢在上手分。但 webapp-testing 的「设计质量」满分不是白给的——下面逐段看它把分挣在了哪里。

三、SKILL.md 逐段拆解

以下引文均为本机 example-skills 插件缓存中该件原文的逐字摘录。

第一段：一句话定使命

To test local web applications, write native Python Playwright scripts.

标题是 # Web Application Testing，正文第一句就把三件事钉死：测试对象（local web applications，不是线上站点）、实现路径（写原生 Python Playwright 脚本，而不是调某个封装好的测试框架）、动作形态（write，让 Claude 现场写脚本，而不是背一套测试用例库）。好的 SKILL.md 开头都是这种密度——一句话同时回答「干什么、怎么干、干到什么边界」。注意 local 这个限定词：它把生产环境压测、线上安全扫描全部划出管辖范围，触发边界干净。

第二段：黑盒教条——全文最值钱的六行

Helper Scripts Available: - scripts/with_server.py - Manages server lifecycle (supports multiple servers)

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 abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

这是整份文件的设计核心，值得逐行读：

• --help first：把 Unix 命令行的老规矩搬给 Agent。--help 输出只有几十行，读源码可能几百上千行——先用最便宜的方式弄清接口，这是给上下文窗口省钱。
• DO NOT read the source：全大写的禁令只出现这一次。作者非常清楚 LLM 的坏习惯——拿到一个脚本路径就想先通读一遍「理解一下」。对人是好习惯，对上下文只有 20 万 token 的 Agent 是自杀行为。
• pollute your context window：作者用的词是「污染」。这个隐喻说明 Skill 作者的设计意识已经从「写文档给人看」进化到「管理一个有限内存的工人的操作规程」。
• abslutely：原文里这个单词就是拼错的（应为 absolutely）。这反而是真实性的注脚——官方件也是手写的，而 Claude 读指令靠意图不靠拼写，错字不影响执行。你自己写 SKILL.md 时不必有错字焦虑。

这一段给所有 Skill 作者的启示是：你的 Skill 不只是教 Agent 干活，还要教它「别看什么」。资源文件写得越强，越要配一条「禁止阅读」的护栏。

第三段：决策树——把自由裁量权收走

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: ...

作者没有用段落描述「根据情况选择合适的方法」，而是画了一棵 ASCII 决策树。两个分叉点选得极准：是不是静态 HTML（决定了要不要起服务器）、服务器是否已在运行（决定了要不要托管）。每个叶节点直接给出下一个动作，没有任何「你可以考虑……」式的松散建议。LLM 在开放选项面前会摇摆，在二叉判断前不会——用判断题代替选择题，是工具型 Skill 提高执行确定性的第一杠杆。

第四段：with_server.py 用法——例子里的细节全是私货

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

单服务器例子看似平平无奇，三个细节都是设计：

• npm run dev + 端口 5173：5173 是 Vite 的默认端口，多服务器例子里的 3000 是后端惯例端口。作者故意用真实世界的默认值，让大多数人拿到的例子和自己的项目严丝合缝，抄过来就能跑。
• --port 5173：脚本要等这个端口真的开始监听才放行后面的命令——「服务就绪检测」这个最容易翻车的点被黑盒吸收了，SKILL.md 一个字都不用解释。
• 裸 --：约定俗成的分隔符，横线之后全是给你的自动化脚本用的参数。两个 --server 可以叠着写，后端前端一次托管——「supports multiple servers」这七个字的承诺由例子兑现。

配套的 Playwright 模板更是把指令埋进了代码注释：

browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute

Claude 写脚本时会整段照抄模板，于是模板里的注释就成了随代码一起被执行的指令：headless 模式和 networkidle 等待，一个管不打扰人、一个管单页应用最大的坑。把行为约束写进被复制的代码，而不是写进希望被记住的散文——这是官方件才有的老辣。

第五段：侦察后行动——不许猜选择器

1. Navigate and wait for networkidle
2. Take screenshot or inspect DOM
3. Identify selectors from rendered state
4. Execute actions with discovered selectors

这个被命名为 Reconnaissance-then-action（侦察后行动）的四步模式，治的是 LLM 自动化测试的头号绝症：幻觉选择器。模型没看过渲染后的页面，会凭 HTML 直觉编一个 page.click('#submit-btn')，然后对着 TimeoutError 死循环。四个步骤的本质是一道铁律——先看渲染结果，再从看到的 DOM 里取选择器，禁止凭空捏造。配套的侦察代码只给三行：全页截图、page.content()、page.locator('button').all()，全是只读动作。

第六段：Common Pitfall——只防一个坑

❌ Don't inspect the DOM before waiting for networkidle on dynamic apps ✅ Do wait for page.wait_for_load_state('networkidle') before inspection

整份文件的「避坑指南」只写了一个坑。这不是偷懒，是克制：作者很清楚 SPA 场景下「DOM 还没渲染完就去查元素」是发生频率最高的失败，把它用 ❌/✅ 对照钉在显眼处；其他次要坑全部降级到 Best Practices 一句话带过。反面教材是那些把十条注意事项平铺的 Skill——权重被摊平，等于没有权重。

第七段：三层资源披露——SKILL.md 只做前台

Reference Files: - examples/ - Examples showing common patterns: - element_discovery.py - Discovering buttons, links, and inputs on a page - static_html_automation.py - Using file:// URLs for local HTML - console_logging.py - Capturing console logs during automation

至此整个件的资源结构清楚了，是一个三层按需加载的体系：

flowchart TD
    L1["第一层 SKILL.md 触发即入上下文"]
    L2["第二层 scripts 黑盒只执行"]
    L3["第三层 examples 按需才读"]
    L1 --> L2
    L1 --> L3

第一层是常驻的 SKILL.md（决策树、模板、铁律）；第二层是 scripts/with_server.py——只准执行不准阅读的黑盒；第三层是 examples/ 里三个示例脚本，每个配一行用途说明（发现页面元素、静态 HTML 用 file:// 协议测、抓浏览器 console 日志），只在撞上对应场景时才值得打开。需要坦白的是，本文对第二、三层也遵循了它的黑盒纪律——只依据 SKILL.md 内文对它们的定位与承诺做拆解，未通读其源码。这恰好是这份 SKILL.md 想教会 Agent 的读法：文件自己把自己的用法说清楚了，读懂前台就够了。

Best Practices 收尾五条也全是省钱逻辑：黑盒优先、用 sync_playwright() 写同步脚本、用完关浏览器、选择器用 text=/role=/CSS/ID 这类语义化写法、按需加等待。没有一条超过一行。

四、适用与不适用

适合交给它的活：

• 本地 dev server 写完后的冒烟自测：「点一遍主要按钮，看 console 有没有报错」
• 前后端分离项目的联调验证（双 --server 托管一次跑通）
• 静态 HTML 原型的结构验证与抓取
• 提 PR 前自己先把 E2E 主路径走一遍，别等 CI 红灯

不适合的活（原文 local 限定 + 模板只给 chromium headless 推出）：

• 线上生产环境的任何测试、压测、安全扫描
• 多浏览器兼容矩阵、移动端真机测试——模板只写了 chromium 无头模式
• 像素级视觉回归对比——它给截图方法，不给 diff 工具
• 性能测试——networkidle 等待策略恰恰是性能测试的大敌

五、安装与使用

本机缓存路径（plugins/cache/anthropic-agent-skills/example-skills/）显示它随 Anthropic 官方的 agent-skills 市场以 example-skills 插件捆绑分发，上游仓库为 github.com/anthropics/skills。实时 Star 数据本次未能联网核验，不做引用。

# 方式一：已装 example-skills 插件的用户零安装
# 在 Claude Code 里直接说：
# 「测一下 localhost:5173 这个页面：逐个点主要按钮，
#   截图并检查 console 有没有报错」

# 方式二：从官方仓库取件（通用做法）
git clone https://github.com/anthropics/skills
cp -r skills/webapp-testing ~/.claude/skills/    # 个人级，全项目可用
# 或复制进项目的 .claude/skills/，随仓库共享给团队

# 依赖一次性装好
pip install playwright
playwright install chromium

六、抄它六条：写你自己的第一个工具型 Skill

1. 第一句钉死边界：干什么、怎么干、不干什么，一句话说完，限定词（local）要舍得写。
2. 给资源配黑盒禁令：脚本强就写上「先 --help，禁止读源码」，把上下文窗口当内存条管理。
3. 判断题代替选择题：用 ASCII 决策树分派路径，别给 Agent 留摇摆空间。
4. 约束埋进被复制的代码：模板注释里的 CRITICAL 会随复制粘贴自动执行，比散文可靠。
5. 避坑只写最高频的一个：❌/✅ 对照，一条就够，多了等于没有。
6. 例子用真实默认值：5173、3000、npm run dev，让读者抄过来就能跑，就是最好的文档。

推荐排行榜

• 最值得拆抄的设计：webapp-testing——上下文经济学的官方教科书
• 新手第一份该读的 SKILL.md：canvas-design——零脚本零依赖，纯看话术怎么塑造输出
• 最像成熟产品流程的：doc-coauthoring——退出条件、用户否决权、新开 Claude 当读者的验收设计一应俱全
• 综合分最高：doc-coauthoring（4.55）——但如果你要写的是「干活型」而非「聊天型」Skill，webapp-testing 才是那本该抄的范本

参考来源

1. webapp-testing SKILL.md 原文（本机 example-skills 插件缓存逐字引录，路径 plugins/cache/anthropic-agent-skills/example-skills/ 下 skills/webapp-testing/SKILL.md）— 本文核心拆解对象
2. doc-coauthoring SKILL.md 原文（同上插件缓存）— 流程型对照样本
3. canvas-design SKILL.md 原文（同上插件缓存）— 审类型对照样本
4. anthropics/skills — 上述示例件的上游官方仓库；本文写作环境未能联网，实时 Star 数与外部评测未予引用，读者可自行核验

[!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 等场景全覆盖。