Verification setup

Give the next agent an executable path to launch a changed build, drive a feature the way a user does, and inspect what a user sees. Its reader opens it cold, mid-task. Automated tests support that judgment but do not replace the agent's own run.

Two modes, detected by whether the project already has a verification skill — any project-local skill that launches, drives, and observes the app, hand-written ones included: Create (none exists) writes <project>-verify-<surface>; Update (one exists) edits that skill under its own name and proves its feature map against the current app. Never write a second skill beside an existing one. A shared skill installed from elsewhere is a harness the project skill calls, used as-is and never edited here. An existing skill that covers one narrow path becomes one feature file, and the skill grows the sections below around it.

Placement

Put the skill where the repo keeps the skills agents load when working in it (.claude/skills/, .agents/skills/, or wherever the others symlink to), never a directory of skills the repo ships to others. With none, infer the team's tools from the agent config the repo carries; ask only when that leaves it open. In a monorepo, each area with a user surface gets its own skill, one area per run. Work on a topic branch in a worktree, commit locally, and leave pushing and the PR to the user.

Create

1. Interview the repo. Answer from code; ask the user only what cannot be observed.
   • Surface: what a user touches and the action and visible result that matter. Pick the primary surface and list the rest; give surfaces separate recipes when their launch or controls differ.
   • Run: the repo's own run task, its ports, env vars, seed data, and auth. When sign-in needs a human, find a test or guest login in tracked config or fixtures and enable it in gitignored local config; with none, report it as the blocker. Values from a deployed environment stay out of the skill.
   • Drive: reuse an existing agent-control recipe or harness — browser specs, PTY helpers, simulator tooling, a debug port — before adding one. A test suite alone does not complete this path.
   • Observe: the visible result, persistent side effects, and the diagnostics an engineer checks on this surface (console and page errors, failed requests, server or daemon logs).
   • Real machine: whether a drive needs the developer's own home, credentials, or account. When it does, bracket every such drive and every one-off command run while interviewing: fingerprint that state by metadata before and after, and fail on any change. A path is read-only only once a bracketed run has shown it.
   • Isolate: walk the source for fixed ports, shared data directories, lock files, and global state. When two instances cannot run side by side, the skill says so and refuses to drive an instance it did not start.