create-verification-skill

创建验证 skill

一个会修改应用的编码 Agent，应该能够按照用户看到的方式证明改动有效。此 skill 会为一个项目编写这样的验证方案，作为一个 skill 存放在 .agents/skills/verify-<app>/ 中，并基于 e2e 构建。配置会启动应用，e2e mcp 会实时驱动应用，测试会固定必须满足的条件，e2e explore 会对应用进行探索式测试，而 .e2e/ 会保存证据。输出是给下一个 Agent 的，不是给人看的。它会在任务进行中首次读到这份内容，而此前从未接触过这个应用。

e2e skill 是 e2e 所有功能的参考。请先阅读它，并链接到它，而不要重复说明。它是同级的 e2e skill，无论此 skill 安装在何处；如果缺少该文件，运行 npx skills add tester-army/e2e 或 npx e2e init 即可安装。npx e2e guide <topic> 会从项目已安装的软件包中打印参考内容；如果两个版本不同，请优先采用该版本。下文提到的主题（setup、writing-tests、mcp、explore、bug-bash、running、debugging）是它的参考文件。

1. 访谈代码库，而非用户

根据代码库回答以下问题，只向用户询问无法观察到的信息。

问题	答案所在位置	它决定什么
界面	用户实际操作的界面，例如 Web UI、iOS 或 Android 应用、API	每个主要界面对应一个技能；其他界面留待后续运行时命名。Web 通过 @e2e-dev/web 运行，iOS 和 Android 通过 @e2e-dev/mobile 运行。没有 UI 的 API 仍需配置 web() 目标，并设置 app.url 和 app.command，以便运行器启动它；其测试只接收 app，并使用 fetch（主题为 writing-tests）。原生桌面应用目前没有 e2e 引擎，说明这一点并停止。同样处理没有任何引擎能够驱动其界面的项目：CLI、库或批处理任务，以及唯一的浏览器输出是原生运行时提示的桌面前端。没有 UI 的 HTTP 服务不属于上述情况；本行通过 web() 驱动它。观察到这一情况后立即停止，不要等到写完之后：指出入口、无法驱动它的引擎，并说明没有生成任何技能
运行	文档中的开发命令、端口、环境变量、种子数据、身份验证	目标的 app.command（主题为 setup）。首次访问时才编译路由的开发服务器会让 Agent 误以为应用出错，因此仓库有生产构建命令时优先使用它
e2e 状态	e2e.config.ts、tests glob、package.json 中的 e2e、.agents/skills/e2e/、.codex/config.toml、.mcp.json 或 .cursor/mcp.json 中的 MCP 服务，以及任何 Playwright 或 Cypress 测试套件	如果界面一行发现了引擎可以驱动的界面，但这里没有任何内容，则先运行 npx e2e init（主题为 setup）。运行此技能即表示请求进行该设置。Init 会为 Claude Code 和 Cursor 注册 MCP；Codex 需要单独添加项目条目（主题为 mcp）。进行实际操作前，检查当前会话是否具备 e2e 工具。现有的 Playwright 或 Cypress 测试套件是定位器、种子数据和登录步骤的最佳来源；请阅读它。如果配置中没有模型，就只运行确定性步骤和 MCP 工具，不做其他操作
观察	轨迹页面、截图、视频、报告，以及应用在文件、数据行、已发送消息和日志中留下的内容	副作用存储决定“证据”部分中列出的内容。现在就找出它们
隔离	两个实例能否并行运行？	app.url 中的端口 0 会为每次运行启动独立应用；command.reuseExisting: true 则连接到该端口上已运行的应用。若共享实例无法复制（例如只有一个数据库或模拟器），则将其写成生成技能中的规则。拒绝同时驱动两个实例，也好过破坏用户会话
命名	包名称或仓库名称	verify-<app> 中的 <app>：小写，不含作用域

如果检出代码后无法直接构建或启动，应先修复，或在生成前准确报告问题。基于损坏的基础编写技能会教错步骤。无关紧要的缺失资源（例如 API 从不提供的静态目录、示例配置）可以由生成的技能创建，并标记为验证脚手架，随后在清理步骤中移除。

如果已存在 verify-<app>/，必须先读取，再进行任何写入。保留其中的 SKILL.md 和功能文件，补充映射中缺少的功能，并且仅在应用与现有内容相矛盾时修改已有文件。

2. 生成技能

编写 .agents/skills/verify-<app>/SKILL.md，并添加 YAML frontmatter。 name: verify-<app> 和 description 必须写明应用名称、界面，以及何时应使用该技能；没有 frontmatter，技能就永远不会注册。若项目包含 .claude/skills/，请按照 e2e init 的方式创建链接：使用相对符号链接 .claude/skills/verify-<app>，指向 ../../.agents/skills/verify-<app>。每个部分都应说明访谈发现的内容，不得使用占位符。

部分	内容
先读	用一句话引导读者阅读 e2e 技能，并指出此技能所驱动的配置文件和 tests glob
启动	启动应用以进行验证的确切命令，以及就绪状态的显示方式。对于包含 app.command 的目标，启动方式为 npx e2e run <smoke file> 或通过 MCP 调用 open_session；运行器会启动应用、等待 URL 就绪，然后停止应用。对于仅包含 app.url 的目标，则说明用户需要手动启动的开发命令，以及证明端口有响应的那一行；或者保留该命令并设置 reuseExisting: true。说明命令所需的端口和环境变量，以及数据的初始化方式
Doctor	一个只读检查，用来回答“这个实例值得操作吗？”。npx e2e list 会加载配置，并列出每个测试与目标的配对，且不会启动任何内容，因此配置错误会最先在这里显现。接着运行 smoke 测试，这是一项无需模型的测试，用于打开应用并确认一个标志性元素；退出码为 0 表示应用已启动、引擎正在运行，且标志性元素已渲染。如果项目中没有 smoke 测试，现在就编写 tests/smoke.e2e.ts。已登录应用的 auth doctor 是一项使用指定会话的常规已登录 smoke 测试：选择该测试会运行其设置步骤并检查恢复后的状态，因此一条命令即可证明应用已启动、会话已恢复，且已登录状态下的标志性元素已渲染。单独运行设置文件时不会选择任何测试，且会以 NO_TESTS 退出，因此它不是 doctor。只要发现任何异常，Agent 都应先运行 Doctor
操作	说明两种操作方式及各自的适用场景。通过 MCP 实时操作：使用 open_session、observe、各类操作动词，并在编写任何定位器之前先调用 locate（主题 mcp）；列出项目工具以及会话目录提供的凭据。脚本化操作：在 tests glob 覆盖范围内编写测试；已知屏幕上显示的名称时使用 screen，流程多变时使用 agent.act（主题 writing-tests）。优先使用稳定句柄、角色和可访问名称、标签、测试 ID、路由。说明已登录操作所使用的凭据和会话
证据	说明证明材料会保留什么以及存放位置。每次运行都会写入 .e2e/report.json；测试失败时会生成 .e2e/results/<test>/trace.md；使用 --trace on 也会为通过的测试生成跟踪文件；使用 --video 会记录操作过程（主题 running）；app.screenshot('<name>') 会保存指定名称的画面（主题 writing-tests）。下一次运行会清空 .e2e/results/，包括 Doctor 运行，因此必须长期保留的证明材料应使用 --output .e2e/proof/<name> 运行，或者在运行其他任何内容之前先将本次运行目录复制出去。说明证明材料的标准（见下文）
Bug bash	说明此应用如何进行 bug bash（主题 bug-bash）：需要编写的 bug-bash 配置（本地应用无法做到的事情、操作姿态、根据访谈选择的隔离方式）、需要初始化的账户、将 .e2e/bugbash/ 添加到 .gitignore，以及 charters 必须源自功能图（第 3 节）的规则。验证标准：只有当 tests/bugbash/<slug>.e2e.ts 在编码该问题的断言处以 ASSERTION_FAILED 失败时，才算发现 bug
清理	说明需要拆除的内容。运行器会停止它启动的应用，close_session 会停止会话启动的应用；用户自行启动的服务仍由用户负责。绝不要按进程名称终止进程；只停止自己启动的内容。清理时移除实例和临时状态（已初始化的账户、脚手架、发现的问题均被驳回的 charters），但绝不删除证据；指出证据的存放位置
辅助工具	技能附带的任何脚本都必须可执行，且技能正文中必须写明其调用方式。需要读者自行逆向分析的脚本不算辅助工具。大多数项目不需要辅助工具；e2e CLI 就是辅助工具
Evidence 部分的证明标准：执行真实的用户路径，
而非内部 setter 或仅供测试使用的端点；记录操作及其
产生的状态，而不只是最终画面；在访谈中发现的存储中验证副作用（写入的文件、
插入的行、发送的消息）；只有在生产环境边界已隔离外部
系统时才使用 mock。当安全路径是 dry run 或测试模式时，应通过监视文件、网络和引用来验证它跳过了什么，而不是相信它的名称。

3. 建立功能地图

创建 .agents/skills/verify-<app>/features/README.md，并为你能从路由、导航、 命令或文档中识别出的每项面向用户的功能各建一个文件，优先列出前三到五项。参照 references/example/verify-playground/， 这是生成器为 e2e playground 应用生成并运行的技能。其入口文件是 SKILL.example.md， 这样客户端就不会把它识别为另一个可安装技能。 索引是一个包含功能、路由、测试文件和状态（tested 或 untested）的表格。每个功能文件都应包含以下这些 H2 标题，并从用户 视角撰写。

H2	内容
Sub-features	该功能由哪些部分组成，每项一行
How to get to it (user POV)	路由、导航、所需账户
Driving it with e2e	锁定该功能的测试文件、重要定位器（使用 locate 检查），以及实时操作的 MCP 步骤
Proof	表示功能正常的可观察最终状态，包括屏幕上和副作用存储中的状态
Charters	此功能的一个或两个 e2e explore 目标，每个目标包含一个区域、一种姿态和一个句子（主题 bug-bash，步骤 2）。写成扇出行 slug|target|agent|charter，以便 bug bash 可以直接粘贴；若某项章程从已登录状态开始，则应注明其 --session，并单独运行
Gotchas	哪些现象看起来像故障但其实不是；本地应用无法做什么

功能地图是项目维护的验证依据，bug bash 会读取其中的章程。当地图列出多个入口时，只验证一个方便的入口是不完整的；bug bash 若跳过地图中的某项功能，就应报告这一缺口。没有测试的功能应在步骤 4 中补上测试，或在索引中标记为 untested。

4. 交付前验证生成的技能

在项目的 shell 中，端到端运行一次技能自身的说明。

1. Doctor：运行技能中提到的 npx e2e list，然后执行冒烟测试；两者都应以 0 退出。
2. 通过测试文件驱动一项已映射的功能。只需一项；映射表的存在是为了让后续运行覆盖其余功能。若缺少测试：现在根据功能文件编写测试，并通过 MCP 检查定位器。
3. 根据映射表中的一份章程进行 Bug Bash：运行 npx e2e explore '<charter>' --config <bug-bash config> --agent <persona> --max-steps 3 --output .e2e/bugbash/<slug>；若章程指定了会话名，还要加上 --session <name>。阅读其 Findings 并进行分类；现在不必验证每条发现。然后阅读 report.json 中本次运行的 run.explore：若最终状态为 aborted，或运行步骤执行的是通用调查而非映射的章程，则 Bug Bash 尚未得到验证，交接时必须说明这一点。步骤可以证明章程确实运行了，而非退出代码：未执行任何步骤的运行也会以 1 退出。以 --max-steps 结束时，会说明本次运行覆盖到的范围。这能验证模型、配置、章程和输出目录，但不能验证应用。如果没有模型，请跳过此步骤，并在交接时说明 Bug Bash 尚未得到验证。
4. 清理，然后确认相关证据仍保存在指定位置。如果清理操作删除了验证证据，则此步骤不合格。

修复失败项；每次迭代失败后也都要运行 Cleanup，避免失败的尝试遗留端口和进程。未经实际运行的生成技能只是草稿，不是可交付成果。将项目恢复到用户原先的状态。生成的技能、其功能映射表、gitignore 条目，以及你新增的任何测试，均属于改动；除非用户另有要求，否则 .e2e/ 输出和 Bug Bash 配置应保持未跟踪状态。

5. 交接

告知用户完成了哪些内容：技能路径、映射的功能及其中哪些已有测试、各项章程、验证运行结果，以及证据路径。运行映射表中的功能，才能确保映射准确。当路由或标签变更导致测试失败时，应在同一次提交中更新功能文件。当应用新增了映射表中没有的功能时，请重新运行此技能；第 1 节说明了如何处理已有映射表。

若项目没有受支持的界面，应在第 1 节停止；交接时报告你观察到的情况，并说明未写入任何内容。

规则

• 根据你观察到的内容生成。任何适用于所有应用的章节，都不算完成。
• e2e 技能中的一句话胜过你自己写的一段话。链接到相应主题。
• 绝不要在生成的技能或映射表中放入密钥。请写明凭据名称（主题 setup）。
• 不要代替用户提交更改。列出你创建的内容。