No scripted way to prove this repo's UI, CLI, or service actually works. Generates an executable .claude/verify.sh gate plus a verify-<app> skill and feature map. Use for 'add verification here'.
No scripted way to prove this repo's UI, CLI, or service actually works. Generates an executable .claude/verify.sh gate plus a verify-<app> skill and feature map. Use for 'add verification here'.
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 two coupled artifacts:
.claude/verify.sh — a fast, always-on gate wired to the Stop hook. It runs automatically every time an agent tries to finish in this repo and blocks it if the repo is broken. This is the piece that turns "I verified it" from a claim into a mechanism.
.claude/skills/verify-<app>/ — the deep, human-and-agent-readable skill that drives the real app, plus a feature map.
verify.sh is the cheap gate that runs constantly; the skill is the expensive drive you invoke deliberately. Both, or neither is worth much: a gate with no drive only proves the code compiles, and a drive nothing invokes never runs.
You 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.
1. Interview the repo, not the user
Answer these from the codebase and only ask the user what you cannot observe. Fan this out — send all of these as multiple Agent tool calls in a single message so they run concurrently, not one after another:
Surface: what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, 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.
what already exists as a fast, non-interactive correctness check? , , , scripts in ; ; ; ; a target. Record the exact invocation and whether it currently passes on a clean tree.
Check:
typecheck
lint
test
build
package.json
cargo check
go vet
pytest
Makefile
Drive: how can an agent interact with the app programmatically? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then a generic recipe: Playwright or the claude-in-chrome MCP for web and Electron, a tmux/PTY harness for CLI/TUI, plain curl 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.
Use subagent_type: "explorer" for the read-only mapping questions and "general-purpose" for anything that must run a command. 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 .claude/verify.sh — the always-on gate
This is the highest-value artifact. A Stop hook at ~/.claude/hooks/verify-gate.sh already exists and looks for exactly this path. It is a silent no-op unless the file is present and executable, so a verify.sh you forget to chmod +x is a verify.sh that does nothing.
The contract, verbatim, and the constraints it forces:
Hook behavior
What verify.sh must therefore do
Runs bash .claude/verify.sh with cwd already set to the project root
Never cd. Use paths relative to the repo root.
Exit 0 lets the agent stop; non-zero blocks it
Exit non-zero if and only if a human would call the repo broken.
Combined stdout+stderr is fed back to the agent as the block reason
Print only what's needed to fix it. Truncate tool output; no full logs.
Fires on every stop, capped at 3 blocks per session
Stay fast (target under 90s) and deterministic.
No human is attached
Never read stdin, never prompt, never open an editor or a browser.
The agent will run it again immediately after fixing
Be idempotent and read-only: no fixtures left behind, no ports left bound.
The failure mode to design against: a check that fails for a reason the agent cannot fix (a dev server that isn't running, a network flake, a missing global tool) burns all three blocks and then the gate silently stops mattering for the rest of the session. So: a check whose prerequisite is absent must SKIP, not FAIL.
Write the file, then chmod +x .claude/verify.sh. Use this shape, keeping the header comment intact and replacing the checks with the real ones you found in the Interview:
#!/usr/bin/env bash# .claude/verify.sh — contract with the Stop hook (~/.claude/hooks/verify-gate.sh)## The hook runs this file with cwd = project root every time the agent tries to finish.# exit 0 -> the agent may stop.# exit !=0 -> the agent is BLOCKED and this script's stdout+stderr is handed back# to it verbatim as the reason to fix. Capped at 3 blocks per session.## Therefore this file MUST:# - never cd (the hook already runs it from the project root)# - never read stdin, prompt, or require anything interactive# - be safe to run repeatedly and concurrently: read-only, no leftover state# - stay fast (target < 90s) — it runs on every single turn-end# - print only what the agent needs in order to fix it, not full tool logs# - SKIP (not fail) any check whose prerequisite is missing; an unfixable# failure just burns the 3-block budget and disables the gate for the session## Deep behavioral verification lives in .claude/skills/verify-<app>/, not here.set -uo pipefail # deliberately NOT -e: report every failing check, not just the first
FAILED=0
TAIL="${VERIFY_TAIL:-25}"run() { # run <label> <command...>local label="$1"; shiftif ! command -v "$1" >/dev/null 2>&1; thenecho"skip $label ($1 not installed)"return 0
filocal out rc
out=$("$@" 2>&1); rc=$?
if [ "$rc" -ne 0 ]; then
FAILED=1
echo"FAIL $label (exit $rc)"printf'%s\n'"$out" | tail -n "$TAIL"echoelseecho"ok $label"fi
}
has_script() { [ -f package.json ] && node -e "process.exit(require('./package.json').scripts?.['$1']?0:1)" 2>/dev/null; }
RAN=0
run_if() { # <label> <cmd...> -- counts what actually executed
RAN=$((RAN+1)); run "$@"
}
# --- Static gate: replace with the exact checks found in this repo ------------# This template is npm-shaped. In a Go, Rust, Python or Makefile repo every has_script is false,# every line prints "skip", and the script exits 0 having verified nothing -- a gate that cannot# fail is not a gate. Replace these three lines with the repo's real commands (go vet ./... &&# go test ./..., cargo clippy, pytest, make check). The RAN counter below is the backstop: it# refuses to report success until at least one check has actually run.
has_script typecheck && run_if typecheck npm run --silent typecheck || echo"skip typecheck (no script)"
has_script lint && run_if lint npm run --silent lint || echo"skip lint (no script)"
has_script test && run_if test npm run --silent test || echo"skip test (no script)"# --- Optional smoke: only if the app is ALREADY up. Never start a server here;# --- the hook has no way to reap it and a stray process poisons the next run.if curl -fsS -m 2 http://127.0.0.1:3000/api/health >/dev/null 2>&1; then
run smoke bash .claude/verify-smoke.sh
elseecho"skip smoke (nothing serving :3000)"fiif [ "$RAN" -eq 0 ]; thenecho"Blocked by .claude/verify.sh: every check skipped, so nothing was verified."echo"This gate is still the npm-shaped template. Point it at this repo's real commands."exit 1
fiif [ "$FAILED" -ne 0 ]; thenecho"Blocked by .claude/verify.sh. Fix the FAIL lines above."echo"For behavior (not just compilation), drive the feature with the verify-<app> skill."exit 1
fiexit 0
Rules for what goes in:
Only checks you personally ran and saw pass on a clean tree. A gate that is red on arrival teaches the agent that red is normal, and it will start working around it.
No check that needs a server the agent didn't start, no check that needs the network, no check that needs credentials. Those belong in the skill's live drive.
If the repo has no fast checks at all, say so out loud rather than shipping a verify.sh that skips everything. An all-skip gate is indistinguishable from no gate — it exits 0 forever. Either add the missing script or tell the user what's missing and why the gate is currently thin.
Prove it by hand both ways before you hand it over: run it on a clean tree (must exit 0), then introduce one deliberate breakage (a type error), re-run, confirm it exits non-zero and the message alone is enough to locate the fault, and revert.
3. Generate the verification skill
Write .claude/skills/verify-<app>/SKILL.md with YAML frontmatter (name: verify-<app> and a description that names the app, the surface, and the situation you'd reach for it in — without frontmatter the skill never registers; a description that only lists slash forms never fires) 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.
Relationship to the gate: one line naming which checks .claude/verify.sh already covers, so a live drive doesn't waste a run re-proving the typechecker.
4. Seed the feature map
Create .claude/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.
5. Prove the deliverables before handing them over
Run the generated skill's 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.
Then confirm the gate is actually armed:
test -x .claude/verify.sh && bash .claude/verify.sh; echo "exit=$?"
test -x failing means the hook will silently ignore your work. A generated skill that was never executed is a draft, not a deliverable; an unarmed verify.sh is not a deliverable at all.
6. Hand off the maintenance loop
Tell the user that maintain-verification-skill keeps both the feature map and verify.sh honest as the app changes, and that it is worth running after any release or any week of heavy feature churn. Suggest a cadence only if they ask.
