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.
仅基于代码库回答以下问题，只有在无法通过观察获取信息时才向用户询问：
  • 交互层面：用户实际接触的是什么？Web UI、CLI/TUI、桌面应用、API、移动应用还是库？一个仓库可能包含多种类型，请选择主要类型并记录其余类型。
  • 启动方式：应用如何在本地启动？优先使用仓库自身文档化的开发命令（package脚本、Makefile、README快速入门指南）。记录端口、环境变量、种子数据、认证信息。
  • 驱动方式：Agent如何以编程方式与应用交互？优先使用现有工具——Playwright/Cypress测试用例、expect脚本、PTY辅助工具、可通过curl调用的端点、调试端口。若没有现有工具，则选择通用方案：针对Web和Electron应用使用浏览器/CDP，针对CLI/TUI使用tmux/PTY工具，针对服务使用普通HTTP。
  • 证据捕获：可捕获哪些验证证据？截图、终端记录、响应体、日志、退出码、数据库状态。
  • 隔离性：能否同时运行两个应用实例（端口、数据目录、配置文件是否独立）？若不能，请在生成的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前置元数据（
name: verify-<app>
和
description
，其中description需指明应用名称、交互层面及适用场景——若无前置元数据，Skill将无法注册），并包含以下章节，每个章节需基于实际调研结果编写（不得留空占位符）：
  • 启动：启动应用进行验证的精确命令，以及判断应用就绪的方式（日志行、端口响应、提示符）。包含销毁步骤。对于短生命周期的CLI或TUI，无需保持服务器运行：启动意味着先构建二进制文件（或安装依赖），然后在独立的PTY或tmux会话中启动每次驱动操作。
  • 诊断：一个只读检查，用于判断「该实例是否值得驱动？」——进程是否运行、版本/构建是否正确、端口是否由我们占用、认证是否有效。每当出现异常时，Agent会首先运行该检查。
  • 驱动：基于仓库实际情况的工具方案，包含真实的选择器/命令，而非示例。优先使用稳定的定位方式（ARIA标签、数据属性、提示符字符串、路由路径），而非坐标和Tab顺序。
  • 证据：需捕获的验证证据类型及其存储位置。明确验证标准：遵循真实用户路径操作，而非内部设置器或仅测试用端点；捕获操作过程及最终状态，而非仅最终界面；验证可见状态的同时，也要验证副作用（文件写入、数据插入、消息发送）；仅在生产边界已隔离外部系统的情况下使用模拟。当安全路径是试运行或测试模式时，需通过观察（文件、网络、Git引用）验证其实际跳过的内容，而非仅依赖其名称：有些试运行仍会访问网络或打开浏览器。
  • 清理：如何销毁本次运行创建的实例。切勿通过进程名终止进程；仅终止你启动的进程。清理操作需移除实例和临时状态，但不得删除证据：验证工件需在销毁后保留在Skill指定的位置。
  • 辅助工具：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
文件，并为每个可识别的用户面向功能创建单独文件（初期目标为3-5个核心功能，可从路由、命令、菜单或文档中提取）。遵循
references/feature-map-example/
中的格式，包含README索引文件和每个功能的单独文件。每个文件需从用户视角回答：功能是什么、如何访问该功能、如何使用工具驱动该功能、哪些可观察的最终状态可证明功能正常工作。四个二级标题为
子功能
、
用户视角的访问路径
、
使用<工具>驱动
和
注意事项
。功能映射是仓库的维护性验证源；当映射中列出其他入口点时，仅驱动一个便捷入口点的验证是不完整的。

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
指令，以便在应用变更时保持功能映射的准确性。仅在用户询问时建议维护频率。