跳到正文
  1. 技能速查
  2. 验证
  3. /pstack:create-verification-skill

/pstack:create-verification-skill

按需点名

一句话给项目做一个「验证技能」,教 AI 像用户一样把功能真用一遍。

什么时候用
还没有办法自动证明功能真能用。新手最该做的一件事。
要一起装
maintain-verification-skill
这样说
/pstack:create-verification-skill

用它和不用它

同一件事,直接跟 AI 说,和点名用 /pstack:create-verification-skill,AI 的做法不一样:

直接说用 /pstack:create-verification-skill
用内部 setter 或测试专用接口证明功能能用走真实的用户路径,再核对写入的文件和数据
清理时把截图和日志这些证据一起删了清理完确认证据还在技能指定的位置
按进程名杀进程,连你在用的实例也关掉只关这次自己启动的实例

文档写了什么

原文分 5 节,约 1050 个英文单词,中文译文约 1850 字,读完约 5 分钟。点一节直接跳到全文。

开头要生成的是项目里的 verify-<app> 技能,用来启动真应用、像用户一样操作、留下证据,写给从没见过这个应用的下一个 AI 看。

  1. 1去问仓库,别去问用户从代码里回答五个问题:用户碰什么、怎么启动、怎么操作、能留什么证据、能不能同时开两个。
  2. 2生成技能写带 frontmatter 的 SKILL.md,分 Launch、Doctor、Drive、Evidence、Cleanup、Helpers 六节,全用仓库里的真命令。
  3. 3先铺好功能地图在 features/ 里先写 3 到 5 个主要功能,每个写怎么进入、怎么操作、看到什么算成功。
  4. 4交出去之前,先证明生成的技能真能用照技能自己的步骤完整跑一遍,测一个功能,清理后证据还在才算过。
  5. 5告诉用户怎么持续维护告诉你以后用 /pstack:maintain-verification-skill 让功能清单跟上应用,你问了才建议多久跑一次。

看写法亮点读全文

写法亮点

挑了几句原文:每句让 AI 做什么、为什么这样写管用、你写提示词时怎么借来用。

  1. 描述读者读它时的处境

    it will be read cold, mid-task, by an agent that has never seen the app.

    读它的 AI 从没见过这个应用,会在任务做到一半时、毫无准备地读它。

    让 AI
    生成的验证技能把命令、端口、准备步骤都写全,换一个从没见过你项目的 AI 也能直接照着跑。
    为什么管用
    说出读的人「什么都不知道、正忙着别的事」,AI 自然会补上它觉得理所当然、其实别人不知道的东西。
    借来用
    让 AI 写交接文档时加一句:「读的人是明天刚来的新同事,没碰过这个项目,手头还有别的急事。」
  2. 能自己查的别问人

    Answer these from the codebase and only ask the user what you cannot observe

    下面这些问题,从代码库里找答案。只有你观察不到的,才问用户

    让 AI
    它先翻代码找启动命令、端口和测试工具,只拿真查不到的事来问你,你不用回答一长串问题。
    为什么管用
    给 AI 一条「先查再问」的分界线,它既不会瞎猜,也不会把能自己找的活推回给你。
    借来用
    布置任务时加一句:「项目里能找到的先自己找,找不到的攒成一条消息一起问我。」
  3. 提前堵住作弊的路

    Never weaken the journey to make it pass.

    绝不为了让它通过而把路径改简单。

    让 AI
    测试过不了时,你会看到失败和原因,而不是一个被悄悄改简单、所以「通过了」的测试。
    为什么管用
    AI 被要求「让它通过」时,最省事的办法是降低标准;先点名这条路不能走,它就只能去找真问题。
    借来用
    让 AI 修失败的检查时加一句:「不许改测试或放宽断言,只能改被测的代码。」
  4. 给「交付」换个名字

    A generated skill that was never executed is a draft, not a deliverable.

    一个从没执行过的生成技能,只是草稿,不是能交付的东西。

    让 AI
    它交给你之前会亲自把新技能从头跑一遍,你拿到的是跑通过的,不是只写好的。
    为什么管用
    把没跑过的东西直接叫「草稿」,AI 就不会觉得写完等于做完。
    借来用
    给交付物下个门槛:「没在手机上打开过的页面只算草稿,别交给我。」

全文

AI 读到的就是这份 SKILL.md。可以看中文、看原文,或者一段一段对照着看。

descriptionGenerate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. Use for /pstack:create-verification-skill, "make a control skill for this repo", or when a project has no scripted way to prove UI/CLI/service behavior.

description生成一个放在项目里的验证技能,让它像用户一样去操作你的应用。任何语言、框架、平台都行。用于 /pstack:create-verification-skill、「给这个仓库做一个操控技能」,或者项目里还没有能用脚本证明界面 / 命令行 / 服务行为的办法时。

Create a verification skill

Create a verification 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 (<skills>/verify-<app>/) tailored to the repo. <skills> is your harness's project skill folder: .cursor/skills/ in Cursor, .claude/skills/ in Claude Code, .pi/skills/ in Pi, .agents/skills/ in Codex, OpenCode, and others. If the repo already keeps skills in one of these, use that one. 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.

每个认真的项目,都需要一个用脚本操作真实应用、证明它的行为的办法:启动它,像用户那样用一遍某个功能,再留下证据。这个技能会把这套办法生成为一个放在项目里的技能(<skills>/verify-<app>/),按这个仓库量身定做。<skills> 是你所用工具的项目技能文件夹:Cursor 里是 .cursor/skills/,Claude Code 里是 .claude/skills/,Pi 里是 .pi/skills/,Codex、OpenCode 等是 .agents/skills/。如果仓库已经把技能放在其中某一个里,就用那一个。你写出来的东西,是给下一个 AI 看的,不是给人看的:读它的 AI 从没见过这个应用,会在任务做到一半时、毫无准备地读它。

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.
  • 界面: 用户实际碰到的是什么?网页界面、命令行 / 终端界面、桌面应用、API、手机应用,还是一个库?一个仓库可能有好几种;挑主要的那一个,其余的记下来。
  • 运行: 应用在本地怎么启动?优先用仓库自己文档里写的开发命令(package 脚本、Makefile、README 里的快速上手)。记下端口、环境变量、种子数据、登录认证。
  • 操作: AI 怎样用程序和它交互?先找已有的工具:Playwright / Cypress 测试、expect 脚本、PTY 辅助工具、能用 curl 调的接口、调试端口。没有才挑一个通用做法:网页和 Electron 用浏览器 / CDP,命令行 / 终端界面用 tmux / PTY 工具,服务用普通 HTTP。
  • 观察: 能留下什么证据?截图、终端记录、响应内容、日志、退出码、数据库状态。
  • 隔离: 能不能同时跑两个实例(端口、数据目录、配置档)?不能的话,就在生成的技能里写明:宁可拒绝同时操作一个共用的实例,也别把用户正在用的会话搞坏。

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.

如果代码原样编译不过或启动不了,生成之前先把它修好(或者准确地报告出来);照着一个坏掉的基础写出来的技能,会教错步骤。如果是一个无关的缺失文件挡住了启动(API 从来不提供的静态目录、一份示例配置),生成的技能可以把它建出来,清楚标明是验证用的临时脚手架,并在清理时删掉。

2. Generate the skill

2. 生成技能

Write <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):

写 <skills>/verify-<app>/SKILL.md,带 YAML frontmatter(name: verify-<app>,再加一个 description,写明应用、界面,以及什么时候该用它。没有 frontmatter,这个技能永远不会被注册),并包含下面这些小节。每一节都要基于访谈中真正查到的东西(不留任何占位符):

  • Launch: the exact command that starts the app for verification, and how to tell it's ready (a log line, a prompt). Launch must reach a usable state from an empty data dir, including any migrations and seed data. Ready means usable, not just that a process answers. A database health check can pass while its init scripts are still running. 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.
  • 启动: 为验证启动应用的确切命令,以及怎么判断它准备好了(某一行日志、某个提示符)。启动必须从一个空的数据目录走到能用的状态,包括所有数据库迁移和种子数据。准备好指的是能用,而不只是有个进程在应答。数据库的健康检查可能已经通过,初始化脚本却还在跑。要写上怎么关掉。如果是运行时间很短的命令行或终端界面程序,就没有要一直开着的服务:启动的意思是先编译出程序(或装好依赖)一次,然后每次操作都在它自己的、隔离的 PTY 或 tmux 会话里开始。
  • 体检: 一个只看不改的检查,回答「这个实例值不值得去操作?」:进程开着、版本 / 构建对、端口是我们占的、登录认证有效。只要看着哪里不对,AI 就先跑这一项。
  • 操作: 操作工具的做法,用这个仓库里真实的选择器 / 命令,不用示例。优先用稳定的抓取点(ARIA 标签、data 属性、提示符文字、路由路径),不用坐标和 Tab 键顺序。
  • 证据: 一次证明要留下什么,放在哪。写明证明的标准:走真实的用户路径,不用内部的设值函数或只给测试用的接口;既要记下操作,也要记下操作后的状态,不能只有最后一屏;除了看得见的,还要核实副作用(写出的文件、插入的数据行、发出的消息);只有在生产环境本来就有一层边界把外部系统隔开的地方,才用模拟替身。如果安全的做法是空跑或测试模式,就靠观察(文件、网络、git 引用)去核实它实际跳过了什么,而不是看名字就信:有些空跑照样会联网,或者打开浏览器。
  • 清理: 怎么关掉这次运行开出来的实例。绝不按进程名去杀进程;你开的是哪个,就杀哪个。清理要删掉实例和临时状态,但绝不删证据:证明用的文件在关掉之后还要留着,放在技能里写明的位置。
  • 辅助脚本: 技能附带的任何脚本都能直接执行,技能正文里要写出怎么调用它。一个要读的人去反推用法的辅助脚本,算不上辅助。

3. Seed the feature map

3. 先铺好功能地图

Create <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. If the seed data lacks a precondition that a journey needs, the journey reports a failure and the reason goes in that feature's Gotchas. Never weaken the journey to make it pass. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.

建 <skills>/verify-<app>/features/README.md,再给你能找到的每个面向用户的功能各建一个文件(一开始先挑最重要的 3-5 个,从路由、命令、菜单或文档里找)。照 references/feature-map-example/ 的样子来:一个 README 索引,每个功能一个文件。每个文件都从用户的角度回答:这个功能是什么,怎么走到它,怎么用操作工具去操作它,以及看得见的哪种最终状态能证明它好用。四个二级标题是 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。如果种子数据里缺了某条用户路径需要的前提条件,这条路径就报失败,原因写进那个功能的 Gotchas。绝不为了让它通过而把路径改简单。这张地图是仓库里长期维护的验证依据;地图上列了别的入口时,只操作一个顺手的入口得出的证明,是不完整的。

4. Prove the generated skill before handing it over

4. 交出去之前,先证明生成的技能真能用

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. If you proved it in a stand-in for the real target (a container in place of a fresh VM, a local stack in place of a remote one), list every setup step the stand-in did that the target will not. Those steps stay unverified until a run on the real target covers them.

把它自己的说明从头到尾跑一遍:启动,体检,操作地图上的一个功能(一个就够了;地图的用处就是让以后的运行去覆盖其余的),留下证据,清理。清理完后,确认证据还在写明的位置上:清理把证据也删了,这一步就算失败。哪里失败就修哪里。每次失败之后,也要跑一遍生成的清理步骤,免得失败的尝试留下没关的进程和被占的端口。一个从没执行过的生成技能,只是草稿,不是能交付的东西。如果你是在真实目标的替代环境里证明的(用容器代替全新的虚拟机,用本地的一套服务代替远程的),就把替代环境做了、而真实目标不会做的每一个准备步骤都列出来。这些步骤在真实目标上跑过一次之前,都算没验证。

5. Offer the maintenance loop

5. 告诉用户怎么持续维护

Point the user at /pstack:maintain-verification-skill for keeping the map honest as the app changes. Suggest a cadence only if they ask.

告诉用户可以用 /pstack:maintain-verification-skill,在应用变化时让地图保持真实。只有用户问了,才建议多久维护一次。

原文作者 Lauren Tan(poteto),MIT 许可。译文由本站翻译,核对到 pstack 镜像 97de40d。 在 GitHub 上看

本站是 pstack 的非官方入门教程,不是官方文档;pstack 由 poteto 开发,命令和行为以官方仓库为准。教程原始源码见 GitHub。

由 airali部署,基于小小东的 MIT 授权教程改编。