create-verification-skill

创建验证技能

每个严肃的项目都需要一种脚本化方式来驱动真实应用并验证其行为：启动应用，像用户一样体验某项功能，并捕获证据。此技能会根据仓库生成一个项目本地技能（.cursor/skills/verify-<app>/）。你编写生成结果的目标是下一个 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. 生成技能

在 .cursor/skills/verify-<app>/SKILL.md 中编写内容，并加入 YAML 前置元数据（name: verify-<app>，以及一个说明应用、界面和何时使用该技能的 description——没有前置元数据，技能就不会注册），并包含以下章节。每个章节都必须以访谈实际发现的内容为依据（不得遗留占位符）：

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

3. 填充功能地图

创建 .cursor/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。此地图是仓库持续维护的验证依据；如果地图中列有其他入口，那么只操作一个方便的入口所得的证明就不完整。

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

完整运行一次技能自身的说明：启动、检查、操作一个已映射的功能（一个就足够；地图的存在是为了让后续运行能覆盖其他功能）、捕获证据并清理。清理后，确认指定位置的证据仍然存在——清理过程中删除证明材料，就无法通过此步骤。修复失败之处，并在每次失败的尝试后运行生成的清理流程，避免未完成的尝试遗留进程和端口。未经实际执行的生成技能只是草稿，不是交付成果。

5. 提供维护循环

告诉用户可通过 /maintain-verification-skill 持续维护地图，确保其内容与应用变化相符。只有用户询问时才建议维护频率。