Back to Details

create-verification-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create a verification skill

创建验证 Skill

Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill (
.cursor/skills/verify-<app>/
) tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.
每个成熟项目都需要一种脚本化方式，以驱动真实应用并证明其行为：启动应用，以用户的方式演练某项功能，并捕获证据。该 Skill 会针对仓库生成一个项目本地 Skill（
.cursor/skills/verify-<app>/
）。你编写的生成器输出是给下一个 Agent 阅读，而不是给人阅读：Agent 会在任务中途、毫无上下文时阅读它，而且此前从未见过该应用。

1. Interview the repo, not the user

1. 探查仓库，而不是询问用户

Answer these from the codebase and only ask the user what you cannot observe:
  • Surface: what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several; pick the primary one and note the rest.
  • Run: how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
  • Drive: how can an agent interact with it programmatically? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.
  • Observe: what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
  • Isolate: can two instances run side by side (ports, data dirs, profiles)? If not, say so in the generated skill: refusing to double-drive a shared instance beats corrupting the user's session.
If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating; a skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.
根据代码库回答以下问题，只询问无法从代码库观察到的信息：
  • 交互面（Surface）： 用户实际接触的是什么？Web UI、CLI/TUI、桌面应用、API、移动应用，还是库？一个仓库可能包含多个交互面；请选择主要交互面，并记录其他交互面。
  • 运行（Run）： 如何在本地启动应用？优先使用仓库自身文档中提供的开发命令（package scripts、Makefile、README quickstart）。记录端口、环境变量、种子数据和认证信息。
  • 驱动（Drive）： Agent 如何以编程方式与应用交互？优先使用现有 Harness，例如 Playwright/Cypress 测试、expect 脚本、PTY 辅助工具、可通过 curl 访问的端点或调试端口。只有在没有现成方案时，才选择通用方案：Web 和 Electron 使用 browser/CDP，CLI/TUI 使用 tmux/PTY Harness，服务使用普通 HTTP。
  • 观察（Observe）： 可以捕获哪些证据？截图、终端记录、响应正文、日志、退出码、数据库状态。
  • 隔离（Isolate）： 能否同时运行两个实例（端口、数据目录、配置文件）？如果不能，请在生成的 Skill 中明确说明：拒绝并行驱动共享实例，远比破坏用户的会话更安全。
如果当前检出的代码无法直接构建或启动，请先修复问题（或准确报告问题），然后再生成 Skill；针对损坏基础编写的 Skill 只会教授错误的步骤。如果启动被一个无关的缺失资源阻塞（例如 API 从不提供的静态目录、示例配置），生成的 Skill 可以创建该资源，但必须明确标记为验证脚手架，并在清理阶段将其移除。

2. Generate the skill

2. 生成 Skill

Write 
.cursor/skills/verify-<app>/SKILL.md
with YAML frontmatter (
name: verify-<app>
and a 
description
that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):
  • Launch: the exact command that starts the app for verification, and how to tell it's ready (a log line, a port answering, a prompt). Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
  • Doctor: one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
  • Drive: the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
  • Evidence: what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
  • Cleanup: how to tear down instances the run created. Never kill by process name; kill what you started. Cleanup removes instances and scratch state, never the evidence: proof artifacts survive the teardown, in a location the skill names.
  • Helpers: any script the skill ships is executable and its invocation is shown in the skill body. A helper the reader has to reverse-engineer is not a helper.
编写 
.cursor/skills/verify-<app>/SKILL.md
，包含 YAML frontmatter（
name: verify-<app>
，以及一个说明应用名称、交互面和使用时机的 
description
——没有 frontmatter，Skill 就无法注册），并包含以下章节。每个章节都必须以实际探查结果为依据，不能留下占位内容：
  • 启动（Launch）： 启动应用进行验证的准确命令，以及判断应用已就绪的方法（日志行、端口响应、提示符）。同时包含停止与清理步骤。对于短生命周期的 CLI 或 TUI，没有需要持续运行的服务器：启动意味着先构建一次二进制文件（或安装依赖），然后在独立的隔离 PTY 或 tmux 会话中启动每次驱动。
  • 诊断（Doctor）： 提供一项只读检查，用于回答“这个实例是否值得驱动？”——进程已启动、版本或构建正确、端口由本次运行的实例占用、认证有效。任何看起来异常时，Agent 都应先运行此检查。
  • 驱动（Drive）： 提供 Harness 配方，并使用仓库中真实存在的选择器或命令，而不是示例。优先使用稳定句柄（ARIA labels、data attributes、prompt strings、route paths），而不是坐标或 Tab 顺序。
  • 证据（Evidence）： 说明需要捕获哪些证明材料，以及保存位置。明确证明标准：演练真实的用户路径，而不是内部 setter 或仅供测试的端点；捕获操作及操作后的状态，而不只是最终画面；除可见结果外，还要验证副作用，例如写入的文件、插入的数据行和发送的消息；只有在生产边界已经隔离外部系统时才能使用 mock。当安全路径是 dry-run 或 test mode 时，应通过观察文件、网络和 git refs 等实际验证它跳过了什么，而不是相信其名称：某些 dry-run 仍会访问网络或打开浏览器。
  • 清理（Cleanup）： 说明如何停止本次运行创建的实例。绝不要按进程名终止进程；只终止自己启动的进程。清理应移除实例和临时状态，但绝不删除证据：证明材料必须在停止实例后继续保留，并存放在 Skill 指定的位置。
  • 辅助脚本（Helpers）： Skill 附带的任何脚本都必须可执行，并在 Skill 正文中展示调用方式。需要读者自行逆向推导的辅助脚本不算合格辅助脚本。

3. Seed the feature map

3. 建立功能映射

Create 
.cursor/skills/verify-<app>/features/README.md
plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in 
references/feature-map-example/
, with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are 
Sub-features
, 
How to get to it (user POV)
, 
Driving it with <harness>
, and 
Gotchas
. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.
创建 
.cursor/skills/verify-<app>/features/README.md
，并为每个可识别的用户功能创建一个文件（可从 routes、commands、menus 或文档中识别，优先覆盖最重要的 3～5 个）。遵循 
references/feature-map-example/
 中的结构，包含一个 README 索引和每个功能对应的文件。每个文件都应从用户视角回答：该功能是什么、如何进入、如何使用 Harness 驱动，以及什么可观察的最终状态能够证明它正常工作。四个 H2 必须为 
Sub-features
、
How to get to it (user POV)
、
Driving it with <harness>
和 
Gotchas
。该映射是仓库持续维护的验证依据；如果映射中列出了多个入口，而一次证明只驱动了其中一个便捷入口，那么这次证明并不完整。

4. Prove the generated skill before handing it over

4. 交付前证明生成的 Skill 可用

Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.
完整执行一次其自身说明：启动、诊断、驱动一个已映射的功能（一个即可；该映射的存在是为了让后续运行覆盖其余功能）、捕获证据并清理。清理后，确认证据仍存在于指定位置——如果清理过程删除了证明材料，则此步骤失败。修复所有失败项，并在每次失败迭代后也运行生成的清理流程，避免失败尝试遗留进程和端口。一个从未执行过的生成 Skill 只是草稿，不是可交付成果。

5. Offer the maintenance loop

5. 提供维护闭环

Point the user at 
/maintain-verification-skill
for keeping the map honest as the app changes. Suggest a cadence only if they ask.
引导用户使用 
/maintain-verification-skill
，以便在应用发生变化时持续维护功能映射的准确性。只有在用户提出要求时，才建议维护频率。