create-verification-skill

创建验证 skill

每个认真的项目都需要一种用脚本操作真实应用、证明其行为的办法：启动应用，像用户那样用一遍某个功能，再留下证据。这个 skill 把这套办法生成为一个按仓库定制的项目本地 skill（.cursor/skills/verify-<app>/）。你写的东西是给下一个 agent 看的，不是给人看的：读它的 agent 从没见过这个应用，会在任务进行到一半时毫无背景地读它。

1. 问仓库，不问用户

下面这些问题从代码库里找答案，只有观察不到的才问用户：

界面： 用户实际接触的是什么？网页 UI、CLI 或 TUI、桌面应用、API、移动应用，还是一个库？一个仓库可能有好几种。挑主要的那一种，其余的记下来。
运行： 应用在本地怎么启动？优先用仓库自己写明的开发命令（package 脚本、Makefile、README 里的快速上手）。记下端口、环境变量、种子数据、鉴权。
操作： agent 怎样用程序和它交互？先找现成的 harness（测试和操作用的脚手架）：Playwright 或 Cypress 的 spec、expect 脚本、PTY 辅助工具、能用 curl 访问的端点、调试端口。都没有，再选一套通用做法：网页和 Electron 用浏览器或 CDP，CLI 和 TUI 用 tmux 或 PTY harness，服务用普通 HTTP。
观察： 能留下什么证据？截图、终端记录、响应正文、日志、退出码、数据库状态。
隔离： 能不能同时跑两个实例（端口、数据目录、配置档）？不能的话，在生成的 skill 里写明：宁可拒绝两边同时操作一个共享实例，也不要弄坏用户的会话。

如果当前代码原样无法构建或启动，先修好（或者把问题说准确），再生成 skill。照着坏掉的基础写出来的 skill，教的步骤就是错的。如果启动被一个无关的缺失文件挡住（API 根本不提供的静态目录、一份示例配置），生成的 skill 可以把它建出来，清楚标明这是验证用的临时脚手架，并在清理时删掉。

2. 生成 skill

写 .cursor/skills/verify-<app>/SKILL.md。文件带 YAML front matter（name: verify-<app>，以及一段写明应用、界面和何时该用的 description。没有 front matter，skill 根本不会被注册），并包含下面这些部分，每一部分都要基于前面实际查到的东西（不留任何占位符）：

Launch： 为验证启动应用的确切命令，以及怎么判断它已就绪（某行日志、某个端口有响应、出现提示符）。写上怎么关掉。对于短命的 CLI 或 TUI，没有需要一直开着的服务：launch 指的是先构建一次二进制（或者装一次依赖），之后每次操作都在独立的 PTY 或 tmux 会话里启动。
Doctor： 一次只读检查，回答「这个实例值得操作吗？」：进程在跑、版本或构建正确、端口归我们、鉴权有效。只要有哪里不对劲，agent 就先跑这一步。
Drive： harness 的操作步骤，用这个仓库里真实的选择器和命令，不是举例。优先用稳定的抓手（ARIA 标签、data 属性、提示字符串、路由路径），不要靠坐标和 Tab 顺序。
Evidence： 证明一件事要留下什么、放在哪里。写明证明的标准：走真实的用户路径，不走内部的 setter 或只供测试用的端点；记录操作本身和操作后的状态，不只是最后一屏；除了看得见的结果，还要验证副作用（写了文件、插了行、发了消息）；只有在生产环境本来就有边界把外部系统隔开的地方，才用 mock。当安全的做法是 dry-run 或测试模式时，要靠观察（文件、网络、git ref）确认它实际跳过了什么，不要看名字就信：有些 dry-run 照样会访问网络或打开浏览器。
Cleanup： 怎样关掉这次运行开起来的实例。绝不按进程名去杀，只杀你自己启动的。清理只删实例和临时状态，绝不删证据：证明材料在关掉实例后依然保留，放在 skill 指定的位置。
Helpers： skill 附带的任何脚本都必须可执行，并在 skill 正文里写出调用方式。读的人还得自己反推怎么用的辅助脚本，不算辅助脚本。

3. 先建起功能地图

创建 .cursor/skills/verify-<app>/features/README.md，再给你能找出的每个面向用户的功能各建一个文件（先从路由、命令、菜单或文档里挑最重要的 3 到 5 个）。照 references/feature-map-example/ 的结构来：一个 README 索引，加上每个功能一个文件。每个文件都从用户的角度回答：这个功能是什么，怎么找到它，怎么用 harness 操作它，以及看到什么样的最终状态就能证明它正常。四个二级标题是 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。这份地图是仓库持续维护的验证依据。地图里列了别的入口，证明却只走了一个方便的入口，这份证明就不完整。

4. 交出去之前先证明生成的 skill 能用

照它自己的说明完整跑一遍：launch、doctor、操作地图里的一个功能（一个就够，地图就是留给以后的运行去覆盖其余功能的）、留下证据、清理。清理之后，确认证据还在指定的位置。清理把证明删了，这一步就算失败。哪里失败就修哪里，每次失败之后也都要跑一遍生成的清理步骤，免得失败的尝试留下没关的进程和占着的端口。一个从没执行过的生成 skill 只是草稿，不是交付物。

5. 告诉用户怎么持续维护

告诉用户用 /maintain-verification-skill 来让地图随着应用变化保持真实。只有用户问起，才建议多久跑一次。