create-verification-skill

Create Verification Skill

把项目中“如何启动、操作、观察和清理”的知识沉淀成 verify-<app>，让下一位 agent 无需当前会话也能验证真实行为。支持 Web、CLI/TUI、服务、桌面、移动端和库；具体工具由仓库与当前环境决定，不依赖特定编辑器、专属工具或 agi-mode。

边界与位置

• 创建或维护验证能力才使用本 skill。已有 verify-*、测试脚本或 harness 能完成一次性验收时，直接执行它们；只要测试计划时使用项目的测试规划流程。
• 输出位置优先级：用户指定 → 项目明确采用的 skill 目录 → .agents/skills/verify-<app>/。存在多个目录时先查项目规则和已有目标 skill，不复制多份、不改全局配置。目录本身不保证宿主自动发现；必要时显式读取生成的 SKILL.md 执行。
• 同一应用已有验证 skill 时原位维护，保留人工补充和调用策略；没有维护授权时只复用或报告缺口。新 skill 的最小 frontmatter 是 name 与 description，不默认限制为仅手动调用。
• 范围是验证能力及必要的本地夹具，不隐含重构产品、安装全局工具或发布。启动受阻时先诊断；已获授权的范围内修复可直接继续，其他情况留下具体阻塞和恢复步骤。

0. 先确定生成范围

从请求与项目事实确定目标应用/工作目录、用户场景、必要前置依赖、判据来源和明确排除项，用一句话说明本轮范围即可，不另建规格文件。多应用仓库只调查目标及实际依赖；无法推导目标且会改变产物时才询问。

请求	生成范围
只为某个 scenario 建立验证能力	只写该场景、指定入口及必要准备/观察，不扩为全应用地图
为应用初始化验证能力，未指定场景	从已确认入口选少量有价值的用户路径，说明首批范围与遗漏，不按数量凑功能
补充或维护已有验证能力	原位增量修改相关配方，沿用功能 ID、人工内容、目录和现有工具

范围必须落实到执行：产物给出选定场景的实际命令、现有测试选择器或按需操作配方。先核对选择范围，再启动有副作用的动作；不支持的场景应报告未覆盖，不能退回全量运行。准备/观察用到相邻入口时说明依赖，不把它们算成已验收功能。一次性验收仍直接用已有能力。

1. 从仓库取得事实

先读仓库规则、启动文档、包脚本、现有测试和相关入口，再做最小运行确认。能从仓库或工具观察到的事实不交给用户填写。

要确认的内容	必须得到的事实
用户入口	用户实际操作的页面、命令、API、设备界面或公开库接口；多个表面分别登记
启动与就绪	工作目录、依赖、构建/启动命令、端口、配置、测试账号/数据及可观察的就绪条件
驱动方式	优先复用现有 Playwright/Cypress、PTY、HTTP 客户端、设备自动化或公开 API 的最小消费者
观测与判据	用户动作、可见结果、持久化副作用如何取得；预期结果来自需求、既有契约或明确的用户行为
隔离与归属	如何分配独立端口、数据目录、浏览器 profile、账号和进程；无法隔离时限制串行，并说明实例归属

不要把 README 中的命令直接当成已验证事实。先确认命令存在、工具可用及实际启动结果；未观察到的选择器、参数或响应不得编造。不能运行的部分标为未验证，不用源码阅读代替运行通过。

每个关键判据指向已读的需求、公开契约或用户明确要求；源码与运行观察说明当前行为，不能单独证明它正确。没有权威预期或来源冲突时，先查关联材料，仍无法确定就标为待确认；可以保存观察配方，但不能据此宣称符合产品要求，也不能以本次实际输出自动生成预期。

共享实例只有在明确允许使用且能界定副作用时才驱动。外部写入沿用已有授权；会发送消息、真实支付或修改共享数据且授权不足时，先完成本地可验证部分，再指出具体缺口。dry-run 或测试模式是否仍联网、开浏览器或写文件，要核对实现及实际行为。

2. 生成项目验证入口

按 产物约定 写出以下内容；该参考供生成时读取，不成为生成结果的运行依赖：

单场景可以只用 verify-<app>/SKILL.md 写清完整配方。多个场景需要独立读取时，再拆成 features/README.md 和 features/<feature-id>.md，共用启动/清理只保留一份。只有重复操作确实需要自动化才添加 scripts/；不预建空目录，不为统一外形增加包装脚本。

生成的 SKILL.md 包含范围选择、启动、只读体检（Doctor）、驱动、证据、清理和结果报告，可按任务合并段落。所有命令从明确的工作目录执行；变量说明如何在本轮产生，跨步骤保留必要路径/进程标识，不留待猜的占位或本机绝对路径。优先直接引用现有测试命令与输出格式，只有缺口确实影响可靠执行才增加最小 helper；写明调用方式并实跑。不得以先跑全图再筛报告的方式实现单场景验证。

证据默认沿用项目约定；没有时存 artifacts/verification/<app>/<run-id>/，与临时数据分开。每轮使用唯一目录，失败尝试也保留。不要把原始日志塞进 .xgent-ai/sdlc/；那里只引用证据和任务状态。

3. 写出场景配方

为本轮范围中的功能/场景分配稳定 ID，写明入口、配方、前置条件和覆盖缺口；单场景内嵌在 SKILL.md，拆分后由 features/README.md 索引。地图是按需导航，不是每次全跑的清单。

每份配方说明用户行为、范围内各入口、前置状态、逐步动作及有来源的可观察判据。标识保持稳定，命令/选择器来自真实项目；UI 操作优先语义角色、可访问名称或稳定属性，CLI/API 使用真实参数和路由。必要的边界、取消、错误与持久化检查随场景列出。

同一功能的按钮、快捷键、CLI 等入口分别记录覆盖，不能因为一个入口通过就把其他入口标为通过。地图保存复用配方；每次运行结果另存证据目录，旧的通过结论不写成永久事实。

4. 实跑并校准

按生成的指令完成一轮：选择范围 → 启动 → Doctor → 所选场景完整路径 → 捕获证据 → 清理 → 确认证据仍在。单场景创建实跑该场景；多场景初始化先跑一个代表路径，其余明确未验证。检查实际动作没有超出所选范围及必要依赖。涉及写入时，从第二个公开入口、重开页面/进程或只读持久层观察确认状态；不能只凭成功提示。

• 新增或可疑的关键断言，用已知好/坏观察样本确认它能接受正确结果、拒绝错误结果。有可控的隔离副本时，再从真实入口执行一个已知故障，例如让保存失效；同时保留正常版本通过的证据。坏数据直接传给比较函数只校准断言，不能称为整条观测链路通过；产品故障注入不得修改用户工作区或共享实例，不能安全执行时标明未验证层级。
• 假绿灯先修观测链路，记录原缺陷并重跑受影响路径；不能降低产品判据。
• 每次失败后也运行本轮清理，检查残留资源和证据路径；只清理本轮创建的进程与临时状态，不按进程名批量杀进程，不删除证据。
• 构建、依赖或认证无法满足时，可以交付明确标记的草稿及已确认事实；没有端到端实跑就不能称为已验证可用。已跑一个功能只证明该路径，不代表整个地图通过。

生成或实质修改后，按 生成结果验收 分开检查发现/选择与实际执行。复杂生成、新增关键 helper 或修改交接流程时，条件允许且委派已获授权则让无生成上下文的独立 agent 从成品冷启动；不把生成者自验称作独立交接验证。冷启动发现缺项时修产物和造成缺项的生成规则，仅重验受影响项。

交付 skill 路径、调用方式、已跑的场景/入口、证据位置、清理结果，以及结构、选择、作者实跑、故障检测和冷启动各层实际验证范围。生成器的冒烟验收与业务任务的完整验收分别说明；没有独立执行条件时如实说明，不虚构已完成的交接。

5. 与 agi-mode 协作

独立调用示例：$create-verification-skill 为当前仓库建立验证能力。也可要求维护已有 verify-<app> 的指定功能。

单场景示例：$create-verification-skill 只为 Notes 的“保存后重新打开仍存在”场景建立验证能力，复用现有测试。

agi-mode 负责结果契约与任务推进，生成的 verify-<app> 负责操作项目和返回可核对的证据。本 skill 只在缺少可复用验证能力且创建/维护属于当前授权时介入，不要求每次进入 AGI 模式先生成文件。

阶段	交接内容
选择检查	agi-mode 将验收项映射到功能 ID、入口与必要边界；复用现有地图，并指出未映射项
执行验证	verify-<app> 接收本轮范围、目标版本/环境、隔离条件和证据位置，只执行所选场景及必要依赖；未知场景不退回全量
返回结果	按功能与入口返回 passed / failed / blocked / not-run、操作、预期与实际结果、证据路径及清理状态
判断完成	agi-mode 对照全部必要验收判断是否完成；跳过、受阻和未执行不能算通过
复用或重验	相关实现、依赖、配置、验证脚本或环境变化时重验受影响项；不能仅重算哈希后沿用旧证据

多阶段任务若已使用 agi-mode 的证据契约，读取已安装 agi-mode 的 references/evidence-contract.md，将功能/入口检查关联到现有 contract 和 receipts，复用其检查器。它只验证记录一致性，不替代真实操作；不复制协议、不强制简单任务建 JSON，也不从生成器冒烟结果推导 SDLC 完成状态。

没有 agi-mode 时，生成的 skill 仍按同样的结果格式独立工作。不要在生成文件中留下对本生成器、其他未安装 skill 或专属工具的隐式依赖。

6. 维护

维护请求沿配方的判据来源和实际命令核对变化，只修改受影响的入口、脚本与共用前置条件，并重跑对应路径；共享准备变化时检查依赖它的场景。新增场景优先扩展原 skill，不复制第二套启动/清理或另建执行框架。保留稳定 ID、人工补充、调用策略和不受影响的文件；无变化不重写。

产品行为未变而验证失效时修配方；真实产品失败保留为失败，不能改预期让它通过。移除过时入口前确认其确已退役，保留其他配方和历史证据。不依赖另一个尚未安装的维护 skill。

维护本生成器时，按需使用 行为验收场景；结构校验与真实执行结果分开报告。