Skip to content
  1. Skills at a glance
  2. Verify
  3. /pstack:create-verification-skill

/pstack:create-verification-skill

Call when needed

In one lineMakes a "verification skill" for your project that teaches the AI to really use each feature like a user.

When to use
You have no automatic way to prove a feature really works. The most useful thing a beginner can do.
Install with
maintain-verification-skill
Say it like this
/pstack:create-verification-skill

Just asking vs. using it

The same request, typed plainly or with /pstack:create-verification-skill. Here's what changes.

Just askingWith /pstack:create-verification-skill
Proves a feature through internal setters or test-only endpoints.Follows the real user path and checks the files and rows it wrote.
Deletes the screenshots and logs along with the cleanup.Confirms the evidence is still at its named location after cleanup.
Kills processes by name, including the instance you are using.Stops only the instances this run started.

What the document says

5 sections, about 1050 words, 5 min to read. Click a section to read it.

OpeningIt generates a project-local verify-<app> skill that launches the real app, drives it like a user and captures evidence, written for an agent who has never seen the app.

  1. 1Interview the repo, not the userAnswers five questions from the code: surface, run command, how to drive it, what evidence exists, and isolation.
  2. 2Generate the skillWrites SKILL.md with frontmatter and six sections, Launch, Doctor, Drive, Evidence, Cleanup and Helpers, using the repo's real commands.
  3. 3Seed the feature mapWrites features/ files for the top 3 to 5 features: how to reach each, how to drive it, what proves it works.
  4. 4Prove the generated skill before handing it overFollows the skill end to end on one mapped feature. It passes only if the evidence survives cleanup.
  5. 5Offer the maintenance loopPoints you to /pstack:maintain-verification-skill to keep the map current, and suggests a schedule only if you ask.

See the wording worth borrowingRead the full text

Wording worth borrowing

A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.

  1. Describe the reader's situation

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

    Makes the AI
    The generated skill spells out commands, ports and setup, so an AI that never saw your project can run it as written.
    Why it works
    Saying the reader knows nothing and is busy makes the AI fill in what it takes for granted but others don't know.
    Borrow it
    For a handover doc, add: "The reader joins tomorrow, has never touched this project, and is juggling something urgent."
  2. Look it up before asking

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

    Makes the AI
    It reads the code for start commands, ports and test tools, and asks you only what it truly can't find.
    Why it works
    A clear "look first, then ask" line keeps the AI from guessing and from handing back work it could do.
    Borrow it
    When you hand over a task, add: "Find what you can in the project first, then ask me the rest in one message."
  3. Block the cheating shortcut

    Never weaken the journey to make it pass.

    Makes the AI
    When a check can't pass you see the failure and why, not a quietly weakened test that "passes".
    Why it works
    Told to make something pass, an AI's cheapest move is to lower the bar; naming that move rules it out.
    Borrow it
    When asking to fix a failing check, add: "Don't edit the test or loosen asserts; change only the code under test."
  4. Rename what isn't done

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

    Makes the AI
    Before handing it over it runs the new skill end to end, so you get one that ran, not one that was only written.
    Why it works
    Calling untested work a "draft" stops the AI from treating written as finished.
    Borrow it
    Set a bar for handoff: "A page you haven't opened on a phone is a draft; don't send it to me."

Full text

The SKILL.md the AI reads, as written.

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.

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.

1. Interview the repo, not the user

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.

2. Generate the skill

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

  • 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.

3. Seed the feature map

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.

4. Prove the generated skill before handing it over

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

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

Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.