create-verification-skill

创建验证技能

每个严肃的项目都需要一种脚本化方式来驱动真实应用并验证其行为：启动应用，像用户一样体验某项功能，并捕获证据。此技能会根据代码仓库生成一个项目本地技能（<skills>/verify-<app>/）。<skills> 是你的测试框架所用的项目技能文件夹：Cursor 中的 .cursor/skills/、Claude Code 中的 .claude/skills/、Pi 中的 .pi/skills/，以及 Codex、OpenCode 等工具中的 .agents/skills/。如果代码仓库已经在这些位置之一存放技能，就使用该位置。你编写生成器的输出，是给下一个 Agent 而不是人类看的：它会由一个从未见过此应用的 Agent 在任务中途首次读取。

1. 了解代码仓库，而不是询问用户

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

• 界面： 用户实际接触的是什么？Web UI、CLI/TUI、桌面应用、API、移动应用，还是库？代码仓库可能包含多个界面；选择主要界面，并注明其余界面。
• 运行： 如何在本地启动应用？优先采用代码仓库自身文档中的开发命令（package 脚本、Makefile、README 快速入门）。注明端口、环境变量、种子数据和身份验证。
• 驱动： Agent 如何通过编程方式与应用交互？先使用已有的测试框架，例如 Playwright/Cypress 测试、expect 脚本、PTY 辅助工具、可通过 curl 调用的端点和调试端口。然后再选择通用方案：Web 和 Electron 使用浏览器/CDP，CLI/TUI 使用 tmux/PTY 测试框架，服务使用纯 HTTP。
• 观察： 可以捕获哪些证据？截图、终端记录、响应正文、日志、退出代码、数据库状态。
• 隔离： 能否让两个实例并行运行（端口、数据目录、配置文件）？如果不能，请在生成的技能中说明：拒绝同时驱动共享实例，也好过破坏用户会话。

如果当前检出的代码无法构建或启动，请先修复（或准确报告问题），再生成技能；基于损坏的基础编写技能会教错步骤。如果无关的缺失资源阻碍了启动（例如 API 不会提供服务的静态目录或示例配置），生成的技能可以创建该资源，但必须明确标记为验证辅助文件，并在清理时移除。

2. 生成技能

编写 <skills>/verify-<app>/SKILL.md，并添加 YAML frontmatter（name: verify-<app> 以及 description，其中需说明应用、界面和适用场景；没有 frontmatter，技能就无法注册）和以下章节。每个章节都必须基于访谈的实际发现（不得留有占位符）：

• 启动： 启动应用以供验证的确切命令，以及如何判断应用已就绪（日志行或提示符）。从空数据目录启动时，必须能进入可用状态，包括执行迁移和写入种子数据。就绪意味着可以使用，而不只是进程有响应。数据库健康检查可能会在初始化脚本仍运行时就通过。说明如何拆除实例。对于短时运行的 CLI 或 TUI，无需保持服务运行：启动意味着构建一次二进制文件（或安装依赖），然后在每个独立的 PTY 或 tmux 会话中启动一次驱动流程。
• 诊断： 提供一项只读检查，回答“这个实例值得驱动吗？”——检查进程是否运行、版本或构建是否正确、端口是否由本实例占用、身份验证是否有效。每当出现异常时，Agent 都应首先运行此检查。
• 驱动： 提供包含本仓库中实际选择器和命令的测试框架方案，而非示例。优先使用稳定的定位方式（ARIA 标签、数据属性、提示字符串、路由路径），而不是坐标和 Tab 键顺序。
• 证据： 说明要为证明捕获哪些内容，以及保存位置。明确证明标准：执行真实用户路径，而非内部 setter 或仅供测试的端点；同时捕获操作和由此产生的状态，而不只是最终屏幕；除了可见内容，还要验证副作用（写入的文件、插入的行、发送的消息）；仅当生产边界已隔离外部系统时，才使用模拟。若安全路径是 dry-run 或测试模式，应通过观察文件、网络、Git 引用等来验证它实际跳过了哪些操作，而不是仅凭名称判断：有些 dry-run 仍会访问网络或打开浏览器。
• 清理： 说明如何拆除本次运行创建的实例。绝不按进程名称终止进程；只终止自己启动的进程。清理应移除实例和临时状态，绝不删除证据：证明材料应保留在技能中指定的位置。
• 辅助工具： 技能随附的任何脚本都必须可执行，并在技能正文中展示其调用方式。需要读者自行逆向工程的脚本不算辅助工具。

3. 初始化功能图谱

创建 <skills>/verify-<app>/features/README.md，并为你能识别的每项面向用户的功能创建一个文件（先根据路由、命令、菜单或文档，选择 3 到 5 项）。遵循 references/feature-map-example/ 中的结构，其中包括 README 索引和每项功能对应的一个文件。每个文件都应从用户视角回答：功能是什么、如何访问、如何通过测试框架驱动，以及哪些可观察的最终状态能够证明它正常工作。四个二级标题为 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。如果种子数据缺少某段用户旅程所需的前置条件，该旅程应报告失败，并在对应功能的 Gotchas 中说明原因。绝不能为了让旅程通过而降低标准。功能图谱是仓库维护的验证依据；如果图谱列出了其他入口点，只通过一个方便的入口点进行驱动的证明就是不完整的。

4. 交付前证明生成的技能有效

端到端运行一次技能自身的指令：启动、运行 doctor、驱动一个已映射功能（一个就够；这份映射是为了后续运行覆盖其余功能）、收集证据、清理。清理后，确认指定位置仍有证据——如果清理操作删除了证据，就不算通过此步骤。修复所有失败之处，并且每次迭代失败后都运行生成的清理操作，以免失败的尝试遗留进程和端口。未经实际运行的生成技能只是草稿，不是可交付成果。如果你是在真实目标的替代环境中验证的（例如用容器代替全新的 VM，用本地技术栈代替远程技术栈），请列出替代环境执行、而目标环境不会执行的所有设置步骤。在真实目标上运行并覆盖这些步骤之前，它们都仍未经过验证。

5. 提供维护流程

引导用户使用 /maintain-verification-skill，以便在应用发生变化时保持映射准确。只有在用户询问时，才建议维护周期。