Back to Details

create-verification-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create a verification skill

创建验证Skill

A coding agent that changes an app should be able to prove the change the way a user would see it. This skill writes that proof recipe for one project as a skill, 
.agents/skills/verify-<app>/
, built on e2e. The config launches the app, 
e2e mcp
drives it live, tests pin what must hold, 
e2e explore
bug bashes it, and 
.e2e/
keeps the evidence. Write the 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.
The e2e skill is the reference for everything e2e does. Read it first and link to it rather than restate it. It is 
.agents/skills/e2e/SKILL.md
in the project once 
npx e2e init
or 
npx skills add tester-army/e2e
ran, and 
npx e2e guide <topic>
prints it from the installed package. Topics named below (
setup
, 
writing-tests
, 
mcp
, 
explore
, 
bug-bash
, 
running
, 
debugging
) are its reference files.
修改应用的编码Agent应当能够以用户的视角证明变更的正确性。本Skill基于e2e为单个项目生成该验证流程的Skill，存放于
.agents/skills/verify-<app>/
。配置会启动应用，
e2e mcp
实时驱动应用，测试固定必须满足的条件，
e2e explore
执行Bug Bash，
.e2e/
目录留存证据。输出内容是写给下一个Agent的，而非人类读者。它会被从未接触过该应用的Agent在任务中途直接读取。
e2e Skill是所有e2e相关操作的参考文档。请先阅读并链接到它，而非重复表述。执行
npx e2e init
或
npx skills add tester-army/e2e
后，它会存在于项目的
.agents/skills/e2e/SKILL.md
路径下，也可以通过
npx e2e guide <主题>
从已安装的包中打印。下文提到的主题（
setup
、
writing-tests
、
mcp
、
explore
、
bug-bash
、
running
、
debugging
）均为其参考文件。

1. Interview the repo, not the user

1. 调研代码库，而非询问用户

Answer these from the codebase and ask the user only what you cannot observe.
QuestionWhere the answer isWhat it decides
SurfaceWhat a user touches. A web UI, an iOS or Android app, an APIOne skill per primary surface; name the others for a later run. Web goes through 
@e2e-dev/web
, iOS and Android through 
@e2e-dev/mobile
. An API with no UI still gets a 
web()
target with 
app.url
and 
app.command
so the runner starts it, and its tests take only 
app
and use 
fetch
(topic 
writing-tests
). A native desktop app has no e2e engine yet, say so and stop
RunThe documented dev command, its ports, env vars, seed data, authThe target's 
app.command
(topic 
setup
). A dev server that compiles a route on first visit reads as broken to an agent, so prefer a production build command when the repo has one
e2e state
e2e.config.ts
, the 
tests
glob, 
e2e
in 
package.json
, 
.agents/skills/e2e/
, the MCP server in 
.mcp.json
or 
.cursor/mcp.json
, and any Playwright or Cypress suite		Nothing there means 
npx e2e init
first (topic 
setup
), which also installs the skill and registers the server. An existing Playwright or Cypress suite is the best source of locators, seeds, and sign-in steps; read it. A config with no model runs the deterministic steps and the MCP tools, and nothing else
ObserveThe trace page, screenshots, video, the report, and what the app leaves behind in files, rows, sent messages, logsThe side-effect stores the Evidence section names. Find them now
IsolateCan two instances run side by side?Port 
0
in 
app.url
gives each run its own app; 
command.reuseExisting: true
attaches to one already running on the port. A shared instance that cannot be duplicated (one database, one simulator) becomes a rule in the generated skill. Refusing to double-drive it beats corrupting the user's session
NameThe package name or the repo name
<app>
in 
verify-<app>
, lowercase, no scope
If the checkout does not build or start as-is, fix that first or report it precisely before generating. A skill written against a broken base teaches wrong steps. An irrelevant missing asset (a static dir the API never serves, a sample config) may be created by the generated skill, marked as verification scaffolding and removed in Cleanup.
An existing 
verify-<app>/
is read before anything is written. Keep its SKILL.md and feature files, add the features the map lacks, and change an existing file only where the app contradicts it.
从代码库中寻找这些问题的答案，仅在无法观察到时才询问用户。
问题答案来源决定内容
呈现层用户接触的部分：Web UI、iOS或Android应用、API每个主要呈现层对应一个Skill；其他呈现层可标注出来供后续运行处理。Web端通过
@e2e-dev/web
驱动，iOS和Android端通过
@e2e-dev/mobile
驱动。无UI的API仍会配置一个带有
app.url
和
app.command
的
web()
目标，以便运行器启动它，其测试仅接收
app
参数并使用
fetch
（主题
writing-tests
）。原生桌面应用目前暂无e2e引擎支持，需说明并停止操作
运行方式文档记录的开发命令、端口、环境变量、种子数据、认证方式目标的
app.command
配置（主题
setup
）。首次访问时才编译路由的开发服务器对Agent来说会被判定为异常，因此如果代码库有生产构建命令，优先使用
e2e状态
e2e.config.ts
、
tests
通配符、
package.json
中的
e2e
字段、
.agents/skills/e2e/
目录、
.mcp.json
或
.cursor/mcp.json
中的MCP服务器配置，以及任何Playwright或Cypress测试套件		若以上均不存在，需先执行
npx e2e init
（主题
setup
），该命令也会安装Skill并注册服务器。已有的Playwright或Cypress测试套件是定位器、种子数据和登录步骤的最佳来源，请务必阅读。未配置模型的配置文件仅会执行确定性步骤和MCP工具，不做其他操作
可观测内容追踪页面、截图、视频、报告，以及应用在文件、数据行、发送的消息、日志中留下的痕迹副作用存储的位置将作为「证据」部分的条目名称，请现在就找出它们
隔离性两个实例能否并行运行？
app.url
中设置端口
0
可为每次运行分配独立的应用实例；
command.reuseExisting: true
则会连接到端口上已运行的实例。无法复制的共享实例（如单个数据库、单个模拟器）会成为生成的Skill中的一条规则：拒绝重复驱动，以免破坏用户的会话
名称包名或代码库名称
verify-<app>
中的
<app>
部分，小写，不含作用域
如果检出的代码无法直接构建或启动，请先修复该问题，或在生成Skill前准确报告。基于损坏的基础编写的Skill会传授错误的步骤。无关的缺失资源（如API从未提供服务的静态目录、示例配置）可由生成的Skill创建，标记为验证脚手架，并在清理步骤中移除。
在写入任何内容前，先读取已有的
verify-<app>/
目录。保留其中的SKILL.md和功能文件，补充功能地图中缺失的功能，仅在应用实际情况与现有文件冲突时才修改已有文件。

2. Generate the skill

2. 生成Skill

Write 
.agents/skills/verify-<app>/SKILL.md
with YAML frontmatter. 
name: verify-<app>
and a 
description
naming the app, the surface, and when to reach for it; without frontmatter the skill never registers. When the project has 
.claude/skills/
, link it the way 
e2e init
does, a relative symlink 
.claude/skills/verify-<app>
to 
../../.agents/skills/verify-<app>
. Every section says what the interview found, no placeholders.
SectionHolds
Read firstOne line that sends the reader to the e2e skill and names the config file and 
tests
glob this skill drives
LaunchThe exact command that starts the app for verification and how readiness shows. With a target 
app.command
, launch is 
npx e2e run <smoke file>
or an 
open_session
over MCP; the runner starts the app, waits for the URL, and stops it. Without one, a target with 
app.url
only, the dev command the user starts by hand, and the line that proves the port answers; or keep the command and set 
reuseExisting: true
. Say which ports and env the command needs and what seeds the data
DoctorOne read-only check that answers "is this instance worth driving?". 
npx e2e list
loads the config and prints every test-target pair without starting anything, so a config error shows here first. Then the smoke test, a model-free test that opens the app and pins one landmark; exit 
0
means the app starts, the engine runs, and the landmark renders. No smoke test in the project: write 
tests/smoke.e2e.ts
now. A signed-in app's auth doctor is its session setup test. An agent runs Doctor first whenever anything looks off
DriveTwo lanes and when to use each. Live over MCP: 
open_session
, 
observe
, the verbs, and 
locate
before any locator is written (topic 
mcp
); list the project tools and credentials the session's catalog offers. Scripted: a test under the 
tests
glob, 
screen
where the name on screen is known, 
agent.act
where the flow varies (topic 
writing-tests
). Prefer stable handles, roles and accessible names, labels, test ids, routes. Name the credentials and sessions a signed-in drive starts from
EvidenceWhat a proof keeps and where. Every run writes 
.e2e/report.json
; a failed test gets 
.e2e/results/<test>/trace.md
, 
--trace on
gives one to passing tests too, 
--video
records the attempt (topic 
running
), 
app.screenshot('<name>')
saves a named frame (topic 
writing-tests
). The next run clears 
.e2e/results/
, Doctor included, so a proof that must outlive it runs with 
--output .e2e/proof/<name>
or its attempt directory is copied out before anything else runs. State the proof standards (below)
Bug bashHow this app is bashed (topic 
bug-bash
): the bug-bash config to write (what the local app cannot do, the postures, the isolation choice from the interview), the accounts to seed, 
.e2e/bugbash/
added to 
.gitignore
, and the rule that the charters come from the feature map (section 3). The verification bar: a finding is a bug only once 
tests/bugbash/<slug>.e2e.ts
fails with 
ASSERTION_FAILED
on the assertion that encodes it
CleanupWhat to tear down. The runner stops the app it started and 
close_session
stops the one a session started; a server the user started stays theirs. Never kill by process name; stop what you started. Cleanup removes instances and scratch state (seeded accounts, scaffolding, charters whose findings were all rejected), never the evidence; name where the evidence is
HelpersAny script the skill ships is executable and its invocation is in the skill body. A helper the reader has to reverse-engineer is not a helper. Most projects need none; the e2e CLI is the helper
Proof standards, for the Evidence section: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not only the final screen; verify side effects (files written, rows inserted, messages sent) in the stores the interview found; mock only where a production boundary already isolates the external system. When the safe path is a dry run or a test mode, verify what it skips by watching files, network, and refs rather than trusting its name.
编写带有YAML frontmatter的
.agents/skills/verify-<app>/SKILL.md
文件。包含
name: verify-<app>
和
description
字段，描述中需说明应用名称、呈现层以及适用场景；没有frontmatter的Skill将无法注册。如果项目中有
.claude/skills/
目录，按照
e2e init
的方式建立链接：创建相对符号链接
.claude/skills/verify-<app>
指向
../../.agents/skills/verify-<app>
。每个部分都需基于调研所得的实际信息编写，不得使用占位符。
章节内容
前置阅读一行内容，引导读者查阅e2e Skill，并说明本Skill所使用的配置文件和
tests
通配符
启动用于验证的应用启动的确切命令，以及如何判断应用已就绪。如果目标配置了
app.command
，则通过
npx e2e run <冒烟测试文件>
或MCP的
open_session
启动；运行器会启动应用、等待URL可用，最后停止应用。如果没有配置
app.command
，即目标仅配置了
app.url
，则说明用户需手动启动的开发命令，以及证明端口已响应的检查语句；也可以保留命令并设置
reuseExisting: true
。需说明命令所需的端口、环境变量，以及种子数据的生成方式
诊断（Doctor）一项只读检查，用于回答“这个实例是否值得驱动？”的问题。
npx e2e list
会加载配置并打印所有测试-目标对，无需启动任何内容，因此配置错误会首先在此处暴露。接下来是冒烟测试：一种无需模型的测试，会打开应用并固定一个关键标识；退出码为
0
意味着应用已启动、引擎运行正常且关键标识已渲染。如果项目中没有冒烟测试，请立即编写
tests/smoke.e2e.ts
。需要登录的应用的认证诊断就是其会话设置测试。只要出现任何异常，Agent都应先运行诊断步骤
驱动两种驱动方式及各自的适用场景。MCP实时驱动：
open_session
、
observe
、各类操作动词，以及在编写任何定位器前先使用
locate
（主题
mcp
）；列出会话目录提供的项目工具和凭证。脚本化驱动：
tests
通配符下的测试文件，屏幕名称已知时使用
screen
，流程可变时使用
agent.act
（主题
writing-tests
）。优先使用稳定的句柄、角色和可访问名称、标签、测试ID、路由。说明登录态驱动所需的凭证和会话起点
证据验证需要留存的内容及存储位置。每次运行都会生成
.e2e/report.json
；失败的测试会生成
.e2e/results/<测试名>/trace.md
，开启
--trace on
时通过的测试也会生成该文件，
--video
会录制执行过程（主题
running
），
app.screenshot('<名称>')
会保存命名截图（主题
writing-tests
）。下次运行会清空
.e2e/results/
目录（包括诊断的结果），因此如果需要长期留存验证结果，需使用
--output .e2e/proof/<名称>
参数运行，或在执行其他操作前将本次运行的目录复制出来。需说明验证标准（见下文）
Bug Bash如何对该应用进行Bug Bash（主题
bug-bash
）：需要编写的bug-bash配置（本地应用无法实现的功能、测试姿态、调研得出的隔离方案）、需要预置的账号、添加到
.gitignore
的
.e2e/bugbash/
目录，以及探索章程来自功能地图（第3节）的规则。验证标准：只有当
tests/bugbash/<slug>.e2e.ts
中对应该问题的断言以
ASSERTION_FAILED
失败时，该发现才被确认为bug
清理需要拆除的内容。运行器会停止它自己启动的应用，
close_session
会停止会话启动的应用；用户手动启动的服务器保持不变。绝对不要通过进程名杀死进程；只停止你启动的内容。清理会移除实例和临时状态（预置账号、脚手架、所有发现均被驳回的探索章程），绝不会删除证据；请说明证据的存储位置
辅助工具Skill附带的任何脚本都必须是可执行的，且调用方式需在Skill正文中说明。需要读者反向工程才能使用的辅助工具不算合格的辅助工具。大多数项目不需要额外的辅助工具；e2e CLI就是辅助工具
（证据章节的）验证标准：测试真实的用户路径，而非内部设置方法或仅测试用的端点；捕获操作过程和最终状态，而非仅最终屏幕；在调研发现的存储位置验证副作用（写入的文件、插入的数据行、发送的消息）；仅在生产环境已有边界隔离外部系统的地方才使用mock。如果安全路径是试运行或测试模式，需通过观察文件、网络和引用来验证它跳过了什么，而非仅信任其名称。

3. Seed the feature map

3. 初始化功能地图

Create 
.agents/skills/verify-<app>/features/README.md
plus one file per user-facing feature you can identify, the top three to five first, from routes, navigation, commands, or docs. Follow references/example/verify-playground/, the skill this generator produced and ran for the e2e playground app. The index is a table of feature, route, test file, and status (
tested
or 
untested
). Each feature file has these H2s, from the user's point of view.
H2Holds
Sub-features
What the feature is made of, one line each
How to get to it (user POV)
Route, navigation, the account it needs
Driving it with e2e
The test file that pins it, the locators that matter (checked with 
locate
), the MCP steps for a live walk
Proof
The observable end state that means it works, on screen and in the side-effect store
Charters
One or two 
e2e explore
goals for this feature, each one area, one posture, one sentence (topic 
bug-bash
, step 2). Written as the fan-out line 
slug|target|agent|charter
, so the bug bash pastes them; a charter that starts signed in names its 
--session
and runs alone
Gotchas
What reads as broken but is not; what the local app cannot do
The map is the project's maintained verification source, and the bug bash reads its charters. A proof that drives one convenient entry point is incomplete when the map lists others, and a bug bash that skips a mapped feature reports the gap. A feature without a test gets one in step 4 or is marked 
untested
in the index.
创建
.agents/skills/verify-<app>/features/README.md
文件，并为你能识别的每个用户可见功能创建单独的文件，优先处理前3到5个核心功能，可从路由、导航、命令或文档中梳理。参考references/example/verify-playground/——这是本生成器为e2e playground应用生成并运行过的Skill示例。索引文件是一个包含功能、路由、测试文件和状态（
tested
或
untested
）的表格。每个功能文件都从用户视角包含以下二级标题。
二级标题内容
Sub-features
该功能的组成部分，每行一个
How to get to it (user POV)
路由、导航路径、所需的账号权限
Driving it with e2e
对应该功能的测试文件、关键定位器（已通过
locate
验证）、实时走查的MCP步骤
Proof
证明功能正常的可观测最终状态，包括屏幕上的表现和副作用存储中的变化
Charters
该功能的一到两个
e2e explore
目标，每个目标对应一个领域、一种测试姿态、一句话描述（主题
bug-bash
第2步）。按照
slug|target|agent|charter
的格式写成单行，方便Bug Bash时直接粘贴；需要登录态启动的章程需注明其
--session
参数，且单独运行
Gotchas
看起来像bug但实际不是的情况；本地应用无法实现的功能
功能地图是项目维护的验证基准，Bug Bash会读取其中的探索章程。如果功能地图列出了多个入口点，仅测试一个方便的入口点的验证是不完整的；如果Bug Bash跳过了已映射的功能，需报告该缺口。没有对应测试的功能要么在第4步补充测试，要么在索引中标记为
untested
。

4. Prove the generated skill before handing it over

4. 交付前验证生成的Skill

Run its own instructions end to end once, from a shell in the project.
  1. Doctor: the 
    npx e2e list
    call the skill names, then the smoke test; both exit 
    0
    .
  2. Drive one mapped feature through its test file. One is enough; the map exists so later runs cover the rest. A missing test: write it now from the feature file, with locators checked over MCP.
  3. Bug bash one charter from the map: 
    npx e2e explore '<charter>' --config <bug-bash config> --agent <persona> --max-steps 3 --output .e2e/bugbash/<slug>
    , plus 
    --session <name>
    when the charter names one. Read its 
    Findings
    and triage; do not verify every finding now. This proves the model, the config, and the output directory, not the app. Without a model, skip this step and say in the handover that the bug bash is unproven.
  4. Cleanup, then confirm the evidence still exists at the named location. A cleanup that eats the proof fails this step.
Fix what fails, and run Cleanup after every failed iteration too, so broken attempts do not strand ports and processes. A generated skill that was never executed is a draft, not a deliverable. Leave the project as the user had it. The generated skill, its feature map, the gitignore line, and any test you added are the change; 
.e2e/
output and the bug-bash config stay untracked unless the user asks otherwise.
在项目的shell中完整执行一次该Skill自身的操作流程。
  1. 诊断：运行Skill中指定的
    npx e2e list
    命令，然后执行冒烟测试；两者的退出码都应为
    0
    。
  2. 通过测试文件驱动一个已映射的功能。只需一个即可；功能地图的存在是为了让后续运行覆盖其余功能。如果缺少对应测试：请根据功能文件立即编写，且定位器需通过MCP验证。
  3. 对功能地图中的一个探索章程执行Bug Bash：运行
    npx e2e explore '<章程>' --config <bug-bash配置文件> --agent <角色> --max-steps 3 --output .e2e/bugbash/<slug>
    ，如果章程指定了会话，需加上
    --session <名称>
    参数。读取其
    Findings
    （发现）并进行分类；无需现在验证每一个发现。这一步是为了验证模型、配置和输出目录是否正常，而非验证应用本身。如果没有配置模型，跳过此步骤，并在交付时说明Bug Bash未经验证。
  4. 执行清理，然后确认证据仍存在于指定位置。如果清理操作删除了验证证据，则本步骤失败。
修复失败的问题，每次迭代失败后也要运行清理，避免失败的尝试遗留端口和进程。从未执行过的生成Skill只是草稿，而非可交付成果。保持项目的原始状态，和用户拿到时一致。生成的Skill、功能地图、gitignore新增行，以及你添加的任何测试文件属于变更内容；
.e2e/
输出目录和bug-bash配置文件默认不被跟踪，除非用户另有要求。

5. Hand over

5. 交付

Tell the user what landed. The skill path, the features mapped and which have tests, the charters, what the proof run showed, and the evidence paths. Running the map keeps it honest. When a route or label changes and a test fails, the feature file changes in the same commit. Rerun this skill when the app grows a feature the map lacks; section 1 says how an existing map is treated.
告知用户生成的内容。包括Skill路径、已映射的功能及哪些已有测试、探索章程、验证运行的结果，以及证据路径。定期运行功能地图能保证其准确性。当路由或标签变更导致测试失败时，功能文件需在同一次提交中更新。当应用新增了功能地图中没有的功能时，重新运行本Skill；第1节说明了如何处理已有的功能地图。

Rules

规则

  • Generate from what you observed. A section that could apply to any app is not finished.
  • One sentence from the e2e skill beats a paragraph of your own. Link the topic.
  • Never put a secret in the generated skill or the map. Name the credential (topic 
    setup
    ).
  • Do not commit on the user's behalf. List what you created.
  • 基于你观察到的实际内容生成。适用于任何应用的通用章节是不合格的。
  • 引用e2e Skill中的一句话胜过自己写一段。请链接到对应的主题。
  • 绝对不要在生成的Skill或功能地图中放入密钥。只需命名凭证即可（主题
    setup
    ）。
  • 不要替用户提交代码。列出你创建的所有内容。