Create Verification Skill

---
name: create-verification-skill
description: 为 VibeValley 的一类改动写验收的一份分册（.agents/skills/vv-acceptance/references/<块>.md）：把「怎么证明这次改动真的能用」变成下一个 agent 照着就能做的步骤。用在：一类改动没有现成的验证办法；你刚花了不少工夫才弄清怎么验证一个改动；同一类问题测试和检查都没拦住、到了用户手里才发现；用户说「写个验证 skill」「把这个验证流程固定下来」「加进验收」「create verification skill」。只写改动后的验证，不写怎么实现功能。
---

# 给验收加一份分册

验收（[vv-acceptance](.agents/skills/vv-acceptance/SKILL.md)）只有一个 skill：入口写共同的沙箱、证据和收拾，每一块的做法是 `references/` 下的一份分册。分册回答一个问题：**改了这一块，怎么在真的程序上看到它对了**。它补的是测试和检查之后的那一段：服务端真的起来、接口真的返回、客户端真的画出来。

这一层是「文字」，排在代码和静态检查后面（[AGENTS.md](AGENTS.md#怎么让-agent-做对)）。所以写之前先过第 1 步。

## 1. 先问能不能不写

按顺序问，答「能」就去做那件事，不写分册：

1. 能不能改代码，让这类错误写不出来（类型、不变量、只留一个入口）？
2. 能不能写成测试或检查，进 `vp run server:check`、`vp run web:check`、`vp run --filter @vibevalley/web e2e`、`vp run docs:verify`？服务端的测试能用 oar 的 `scriptedRuntime`、真的 git 仓库和照脚本回答的模型（`@vibevalley/ai/testing`），页面的 Playwright 对着真的服务端，大部分行为都能这样测。

只有要真的跑起来看、要判断（画面对不对、交互顺不顺、真的帮工能不能开工）的，才写分册。一份分册里能改成检查的步骤，也宜改成检查，分册里只留一句命令。

已有的分册管得住的（同一块地方的新改动），改那份，不另写。

## 2. 先真的验证一次

不照着想象写。在这次改动上把验证完整做一遍，边做边记：

- 每条命令原样记下，连同工作目录和环境变量。
- 每一步看到了什么：输出的哪一行、接口返回的哪个字段、截图里的哪个东西，说明成功。
- 哪里卡住了、怎么绕过去的：端口占用、要先生成、服务端不自动重载、要临时的家目录。
- 做完要收拾什么：停掉的进程、删掉的临时目录。

做不完的步骤不写进分册，或者明写「这一步还没走通」。

## 3. 写分册

放在 `.agents/skills/vv-acceptance/references/<块>.md`，`<块>` 用实际的概念或目录名（`server`、`page`、`mobile`），不用皮的叫法。分册没有 frontmatter：agent 什么时候读它，由入口的表决定。

开头一句指回入口（`[验收](.agents/skills/vv-acceptance/SKILL.md)的一份分册`），说它证明什么。正文用这几节，名字固定，`vp run docs:verify` 会查：

- `## 什么时候用`：哪些路径、哪类改动；哪些改动只跑检查就够、不用它。
- `## 准备`：要先有什么（生成的代码最新、构建、模拟器、钥匙），每条带命令。
- `## 步骤`：编号列表，一步一条命令或一个动作，动词开头。要服务端的，用入口的沙箱（`vpx scripts/verify-server.ts -- …`），不另起。
- `## 证据`：做完要拿给用户看的东西：命令的哪几行输出、接口的哪个字段、截图。
- `## 出错时`：这一块常见的失败、怎么认出来、怎么办；沙箱自己的失败入口已经写了，不重复。
- `## 收拾`：停进程、删临时目录。

要花钱、连网、动用户东西的，在入口里也写一句，让没读分册的 agent 也看得到。

写法照 [docs/style/writing.md](docs/style/writing.md)：一步一件事，命令放在代码块里，原样能复制。

## 4. 从头照着做一遍

开一个新的子 agent（或清掉上下文），只给它 vv-acceptance 和一个改动，让它照着验收。它卡住的地方，就是分册（或入口的表）漏写的地方；补上再试，直到它不问问题就能做完。

## 5. 登记

1. 在 [vv-acceptance 的入口](.agents/skills/vv-acceptance/SKILL.md)「什么时候用」的表里加一行：改了什么、读哪份、证明什么；入口的 `description` 补上触发它的路径和说法。
2. 跑 `vp run docs:verify`：它查每份分册有那几节，入口的表正好列全分册。

## 维护

分册是当前的文档，不是历史：命令、路径、端口变了，同一个改动里改它。某一步后来变成了检查，就把那一步换成检查的命令。一份分册里的步骤全都成了检查，就删掉它和入口表里的那一行。