前言¶
常見一類失敗：模型說完「代碼已修復、測試全部通過」，你把 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
