用途
该技能用于生成一个项目本地的“验证技能”,目标是让代理能够像用户一样驱动真实应用,并证明行为确实发生:启动应用、按用户路径操作某个功能、采集证据。生成结果面向“下一个代理”,而不是面向人类——它会在任务中途被从未见过该应用的代理冷读,因此内容必须具体、可执行。
主要能力
- 通过访谈代码库来收集事实,而不是依赖用户口述:
- Surface:用户实际接触什么(Web UI、CLI/TUI、桌面应用、API、移动应用、库),仓库可能有多个,选择主要表面并记录其余。
- Run:应用如何本地启动,优先使用仓库自有开发命令(package scripts、Makefile、README quickstart),并记录端口、环境变量、种子数据、认证。
- Drive:代理如何以编程方式交互,先找既有 harness(Playwright/Cypress 规格、expect 脚本、PTY 辅助、可 curl 的端点、调试端口),再选择通用方案(Web UI 用 preview_* 工具,包括 preview_recording_start / preview_recording_stop 录制视频;Electron 用调试端口上的 CDP;iOS/Android 模拟器用 device_* 工具;CLI/TUI 用 shell 中的 tmux/PTY harness;服务用普通 HTTP)。
- Observe:可采集的证据(截图、终端记录、响应体、日志、退出码、数据库状态)。
- Isolate:能否并行运行两个实例(端口、数据目录、配置文件);若不能,生成技能中要说明,拒绝双重驱动共享实例胜过破坏用户会话。
- 若检出代码无法按原样构建或启动,先生成前修复或精确报告;针对损坏基线写出的技能会教错步骤。若无关的缺失资产阻塞启动(API 从不提供的静态目录、示例配置),生成的技能可创建它,但须明确标记为验证脚手架并在清理时移除。
生成内容
- 创建真实目录 .agents/skills/verify-<app>/,以及相对符号链接 .claude/skills/verify-<app> -> ../../.agents/skills/verify-<app>,使 Claude Code 与 Codex 线程都能加载。两者都要提交。
- 写入 SKILL.md,包含 YAML frontmatter(name: verify-<app> 与一个描述,描述中要写明应用名、表面以及何时使用——没有 frontmatter 技能不会注册),并包含以下章节,每个都基于访谈实际发现(不留占位符):
- Launch:启动验证用应用的精确命令,以及如何判断就绪(日志行、提示符)。启动必须能从空数据目录到达可用状态,包括迁移与种子数据。就绪意味着可用,而不只是进程响应。数据库健康检查通过时其初始化脚本可能仍在运行。包含 teardown。对于短生命周期 CLI 或 TUI,没有需要保活的服务器:启动意味着构建二进制(或安装依赖)一次,然后每次驱动都在自己的隔离 PTY 或 tmux 会话中开始。
- Doctor:一个只读检查,回答“这个实例是否值得驱动?”——进程是否运行、版本/构建是否正确、端口是否由我们占用、认证是否有效。代理在察觉异常时应首先运行它。
- Drive:使用来自该仓库的真实选择器/命令的 harness 配方,而非示例。优先稳定句柄(ARIA 标签、data 属性、提示字符串、路由路径)而非坐标与 Tab 顺序。
- Evidence:证明需要采集什么、放在哪里。说明证明标准:走真实用户路径,而非内部 setter 或仅测试端点;采集动作与结果状态,而不只是最终画面;验证副作用(写入的文件、插入的行、发送的消息)与可见内容;仅在已有生产边界隔离外部系统处使用 mock。当安全路径是 dry-run 或测试模式时,要通过观察(文件、网络、git refs)验证它实际跳过了什么,而不是信任其名称:有些 dry-run 仍会访问网络或打开浏览器。
- Cleanup:如何拆除本次运行创建的实例。绝不按进程名杀进程;只杀自己启动的。清理移除实例与临时状态,但绝不移除证据:证明产物在 teardown 后仍存活于技能指定的位置。
- Helpers:技能附带的任何脚本都必须是可执行的,其调用方式写在技能正文中。需要读者逆向理解的辅助脚本不算辅助。
功能地图
- 在生成的技能目录中创建 features/README.md,并为可识别的每个用户可见功能创建一个文件(起步目标 3-5 个,来自路由、命令、菜单或文档)。遵循 references/feature-map-example/ 的结构:README 索引加每个功能一个文件。
- 每个文件从用户视角回答:该功能是什么、如何到达、如何用 harness 驱动、什么可观察最终状态证明其有效。四个 H2 为 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。
- 若种子数据缺少某旅程所需前置条件,旅程报告失败,原因写入该功能的 Gotchas。绝不削弱旅程使其通过。地图是仓库维护的验证来源;当地图列出多个入口点时,只驱动一个便利入口的证明是不完整的。
交付前证明
- 将生成技能自身的说明端到端跑一遍:启动、doctor、驱动一个已映射功能(一个就够;地图的存在是为了后续运行覆盖其余)、采集证据、清理。
- 清理后确认证据仍存在于指定位置——清理吃掉证明则此步失败。修复失败项,并在每次失败迭代后也运行生成的清理,避免损坏尝试遗留进程与端口。
- 从未执行过的生成技能只是草稿,不是交付物。
- 若在替身环境中证明(用容器代替全新 VM、用本地栈代替远程栈),列出替身做了而目标不会做的每个设置步骤。这些步骤在真实目标运行覆盖前保持未验证。
维护
- 指向 /maintain-verification-skill,用于在应用变化时保持地图真实。仅当用户询问时才建议节奏。
限制与暂未提供
- 资料未提供具体语言、框架或平台的支持范围清单,仅说明“任意语言、框架或平台”。
- 资料未提供安装命令、依赖清单、版本要求或收费信息。
- 资料未提供具体支持的 harness 的完整列表或配置示例。
- 资料未提供生成技能在真实目标而非替身上验证的步骤。