前言¶
常见一类失败：模型说完「代码已修复、测试全部通过」，你把 PR 打开，发现测试一条没跑，日志里还有红叉；或者它说「构建成功」，实际只是它觉得自己构建成功。这类失败的共同点是断言先于证据。本文介绍的 verification-before-completion 就是针对这一点的约束型 Skill：在提交或创建 PR 之前，先跑验证命令、读输出，再决定能不能声明完成。
这是什么¶
一句话定位：一个用于「完成声明」环节的验证前置规范，属于通用 SKILL.md 格式的 Skill，没有可执行脚本、不提供任何 API，也不需要 API Key（官方标签 requires_api_key=false）。
官方页面信息：
- Skill 名称：
verification-before-completion - 坐标：
@org-02qudk26/verification-before-completion-zh - 版本：1.0.0
- 分类：
dev-programming - 来源：enterprise，发布者「智雨科技」
- 官方地址：https://api.skillhub.cn/org-02qudk26/verification-before-completion-zh
官方简介原文如下，也正是它的作用边界：
在声称工作已完成、已修复或通过测试时使用——在提交或创建 PR 前，必须先运行验证命令并确认输出才能声明成功；证据先于断言
它解决的不是「怎么跑测试」，而是「什么时候可以宣称跑过了」。模型通常倾向于通过输出结论而不是完整执行流程，这个 Skill 把验证动作固定到提交前的最后一个环节。
页面上的公开数据为：评分 100000，下载 955，安装 0。安装量为 0 与它新上架、尚未规模化使用相符，说明部署时要自己验证一遍在当前项目里是否生效。
核心功能¶
可以落地的约束只有三条，均来自官方简介：
- 触发时机：当需要声称工作已完成、缺陷已修复、或测试已通过时，先触发该 Skill，而不是直接写结论。
- 验证动作：在提交或创建 PR 之前，必须先运行对应的验证命令（测试、构建、lint、类型检查等），并拿到真实输出。
- 声明条件：确认输出符合预期之后，才能给出「完成 / 修复 / 通过」这类结论；输出不清或者命令没跑，就不能声称成功。
关键词是「证据先于断言」：任何成功结论都要能指到一条实际执行的命令和它的输出上。
安装与启用¶
本次抓取中，官方页面与 SkillHub 页面均未返回正文，因此官方没有给出可直接核对的安装命令。下面的做法基于这类任务给出的通用约定——即按 SKILL.md 格式放置——而非该 Skill 的官方文档，落地前请用官方渠道确认。
以通用 SKILL.md 形式启用，做法是把 Skill 放进项目的 Skill 目录，让代理在运行时加载：
<project-root>/
└── .agents/
└── skills/
└── verification-before-completion/
└── SKILL.md
一个 SKILL.md 文件的骨架通常包含 frontmatter 声明名称，以及正文中的触发场景和流程说明：
---
name: verification-before-completion
description: 在声称工作已完成、已修复或通过测试时使用；提交或创建 PR 前必须先运行验证命令并确认输出。
---
# verification-before-completion
## 何时使用
当需要声称工作已完成、缺陷已修复、或测试已通过时。
## 流程
1. 运行项目的验证命令（测试 / 构建 / lint / 类型检查）。
2. 读取并确认命令输出。
3. 只有在输出符合预期时，才声明完成。
不同代理的加载入口有差异，这也是需要按环境验证的部分：
- Cursor：常放在项目内的 Skill / 规则目录中（如
.cursor/下的对应位置），具体目录以 Cursor 当前文档为准。 - Codex CLI：从项目内 Skill 目录加载，不自动读取官方注册表的远程副本。
- Claude Code / 通用代理：多数按 agent 的 Skill 加载约定查找项目内 SKILL.md。
三类环境都没有官方说明时，通用做法是把上述目录结构放到项目根，再在该代理里触发一次「声称完成」的场景，检查它是否先跑命令。
典型用法¶
以下是依据官方简介可复现的流程示例，命令需按具体项目替换。
第一步，明确要验证的目标，例如修复一个登录失败的问题：
修复登录接口对过期 token 的处理，用户名为 user@example.com 时返回 401
第二步，跑验证命令并取回输出：
npm test -- --grep "expired token"
npm run build
第三步，核对输出确为通过或者确为预期后，再写结论；如果命令报错，先把错误交回去重做，而不是声称已修复。
最终给出的回复应当形成证据链，例如：
- 运行 `npm test -- --grep "expired token"`：12 项通过，0 项失败
- 运行 `npm run build`：构建成功，无类型错误
- 结论：过期 token 已能正确返回 401
反之，未跑命令就写「已修复，测试通过」属于该 Skill 明确禁止的输出。
适用场景与注意¶
适合的人和场景：
- 经常用代理改完代码直接提 PR、并且希望 PR 前有自动验证的开发者和团队。
- CI 已有门槛但代理本地从未跑过验证的仓库环境。
- 对结论可信度敏感的任务（缺陷修复、接口实现、迁移改写），不适用于纯文档润色、重命名搜索这类没有验证命令的任务。
限制与坑：
- 它不提供验证命令：需要自己写清跑什么命令、按什么条件算通过，否则代理会用「看起来通过」替代实际执行。
- 不同项目验证方式不同：Node 项目用 npm / pnpm，Python 用 pytest，Go 用 go test；这些差异要写进项目侧的约定，不能依赖 Skill 自行推断。
- 验证耗时可能被跳过：全量测试较慢时，代理倾向于省略；应对办法是约定允许使用的最小验证子集，并写明范围。
- 安装与加载未在官方文档中确认：本次未能取到官方安装说明，不同编辑器的目录位置也不同，落地后需自行验证是否真正生效。
- 页面公开数据偏低的安装量意味着没有现成案例可参考：遇到行为与预期不符时，回到官方简介的三条约束逐条核对。
结尾¶
这个 Skill 的价值不在于新能力，而在于把「完成」这个词的门槛抬到可核对的位置：提交或创建 PR 之前先有验证命令的输出，再谈成功。对于希望代理产出的每一次完成声明都能被验证的团队来说，是直接可用的约束；但如果项目本身没有可靠的测试或构建命令，它的效果也会打折。
官方地址：https://api.skillhub.cn/org-02qudk26/verification-before-completion-zh
SkillHub 页面：https://www.skillhub.cn/skills/org-02qudk26/verification-before-completion-zh
