--- name: create-verification-skill description: "生成一份项目本地的验证 skill,按用户的方式驱动你的应用。任何语言、框架或平台。用于 /create-verification-skill、「给这个仓库做一份控制 skill」,或项目没有脚本化的办法来证明 UI、CLI 或服务行为的时候。" disable-model-invocation: true --- # 创建验证 skill 每个认真的项目都需要一种脚本化的办法来驱动真实应用并证明行为:启动它,按用户的方式操练一个功能,并抓下证据。这个 skill 把那一份东西生成为按仓库定制的项目本地 skill(`.cursor/skills/verify-/`)。你把生成器的产出写给下一个 agent,不是写给人:它会在任务中途被冷读,读它的 agent 从没见过这个应用。 ## 1. 问仓库,不问用户 从代码库回答这些,只有你观察不到的才问用户: - **表面:** 用户实际碰到的是什么?Web UI、CLI/TUI、桌面应用、API、移动应用、库?一个仓库可以有好几个。选主要的那个,其余的记下来。 - **运行:** 应用在本地怎么启动?优先用仓库自己写下来的开发命令(包脚本、Makefile、README 快速上手)。记下端口、环境变量、种子数据、认证。 - **驱动:** agent 怎样用程序和它交互?先看已有的 harness:Playwright/Cypress 规格、expect 脚本、PTY 辅助、可以 curl 的端点、调试端口。然后才选一个通用配方:网页和 Electron 用浏览器/CDP,CLI/TUI 用 tmux/PTY harness,服务用普通 HTTP。 - **观察:** 能抓下什么证据?截图、终端记录、响应体、日志、退出码、数据库状态。 - **隔离:** 两个实例能不能并排跑(端口、数据目录、配置档)?不能的话,在生成的 skill 里说出来:拒绝去双开一个共享实例,好过弄坏用户的会话。 检出本身构建不了或启动不了时,先修那个(或精确地报告它),再生成。对着一个坏底子写的 skill,教的是错步骤。一个无关的缺失资产挡住启动时(API 从不提供的静态目录、一份示例配置),生成的 skill 可以创建它,清楚地标成验证脚手架,并在清理时去掉。 ## 2. 生成 skill 写 `.cursor/skills/verify-/SKILL.md`,带 YAML frontmatter(`name: verify-`,以及一个 `description`:点名应用、表面,以及什么时候伸手拿它。没有 frontmatter,skill 永远不会注册),再加上这些节。每一节都落在访谈实际发现的东西上,不留占位符: - **启动:** 为验证启动应用的确切命令,以及怎么判断它就绪(一行日志、一个提示符)。启动必须能从空的数据目录到达可用状态,包括任何迁移和种子数据。就绪意味着能用。进程有应答还不够。数据库健康检查可以通过,而它的初始化脚本还在跑。包括拆除。短命的 CLI 或 TUI 没有要保活的服务器:启动意味着把二进制构建一次(或装一次依赖),然后每次驱动在它自己隔离的 PTY 或 tmux 会话里开始。 - **诊断:** 一个只读检查,回答「这个实例值得驱动吗」:进程在、版本或构建对、端口是我们的、认证有效。任何东西看起来不对时,agent 先跑这个。 - **驱动:** harness 配方,用这个仓库里真实的选择器或命令,不要用例子。优先稳定句柄(ARIA 标签、数据属性、提示字符串、路由路径),不要用坐标和 Tab 顺序。 - **证据:** 一份证明要抓什么,以及放到哪里。写明证明标准:操练真实的用户路径,不要用内部 setter 或仅测试的端点。抓下动作和随之而来的状态,不只是最终画面。副作用(写下的文件、插入的行、发出的消息)和看得见的东西一起核。只有生产边界已经把外部系统隔开的地方才用 mock。安全路径是演练或测试模式时,用观察来核它实际跳过了什么(文件、网络、git 引用),不要相信它的名字:有些演练仍然会碰网络或打开浏览器。 - **清理:** 怎样拆除这次运行创建的实例。绝不要按进程名杀。杀你启动的那个。清理去掉实例和临时状态,绝不去掉证据:证明产物在拆除之后还在,位置由 skill 点名。 - **辅助:** skill 带上的任何脚本都是可执行的,调用方式写在 skill 正文里。读者必须反向工程才能用的辅助,不是辅助。 ## 3. 种下功能地图 创建 `.cursor/skills/verify-/features/README.md`,再加上你能认出的每个面向用户的功能各一个文件(先瞄准最上面的 3 到 5 个,从路由、命令、菜单或文档来)。形状遵循 [`references/feature-map-example/`](references/feature-map-example/),一份 README 索引,每个功能一个文件。每个文件从用户的视角回答:这个功能是什么,怎么到达,怎么用 harness 驱动,什么样的可观察终态证明它能工作。四个 H2 是 `Sub-features`、`How to get to it (user POV)`、`Driving it with ` 和 `Gotchas`。种子数据缺一条旅程需要的前提时,旅程报告失败,原因写进那个功能的 `Gotchas`。绝不要把旅程放宽来让它通过。地图是仓库维护着的验证来源。地图还列了别的入口时,只驱动一个方便入口的证明是不完整的。 ## 4. 交出去之前先证明生成的 skill 把它自己的指示端到端跑一次:启动、诊断、驱动一个已映射的功能(一个就够。地图在,是为了以后的运行能覆盖其余的)、抓证据、清理。清理之后,确认证据仍在被点名的位置。吃掉证明的清理,这一步失败。修掉失败的地方,每次失败的迭代之后也跑生成的清理,这样坏掉的尝试不会留下进程和端口。一份从没执行过的生成 skill 是草稿,不是交付物。你是在真实目标的替身上证明的话(一个容器代替一台新虚拟机,一套本地环境代替远程的那套),列出替身做了、目标不会做的每一步搭建。这些步骤一直未验证,直到一次跑在真实目标上的运行覆盖它们。 ## 5. 给出维护循环 把用户指到 `/maintain-verification-skill`,让地图在应用变化时保持诚实。只有他们问,才建议节奏。