Create a Project Verification Skill

Produce a reusable project-owned verification skill, not generic test advice. The result is an actual SKILL.md plus only the approved helpers required to operate it. Prefer the project's existing commands and harnesses over a new control layer.

Workflow

1. Establish the owner

Inspect the repository before proposing files. Read references/discovery-and-safety.md and complete its discovery pass.

Find the owning package, repository instructions, installed versions and tools, command help, test support, existing local skills, and any established skill location. Reuse or deliberately update an existing verification skill or harness rather than creating a parallel one.

If the repository has no established location, propose .agents/skills/<unique-project-verification-name>/SKILL.md. Use a portable project-local path; do not impose a host-specific directory.

Complete when: the project owner, skill owner/location, current verification assets, exact working directories, and relevant commands are evidenced from the repository.

2. Define the recurring job

Name the precise job the generated skill will repeat. Select only the applicable product surfaces:

• browser or app interaction;
• HTTP, service, or API behavior;
• CLI, TUI, or process behavior.

Define named journey contracts with preconditions, public actions, observable completion, and any externally visible persisted effect. Read references/generated-skill-contract.md and apply its complete execution-budget, cancellation, cleanup, port-selection, and blocked-status contract before designing the artifact. A parser or unit-only claim stays at its programmatic boundary; do not manufacture a browser journey for it.

Complete when: every proposed journey states what real behavior it proves, at which boundary, and what remains unsupported.

3. Present a bounded proposal

Before any durable write, package/config change, stateful journey, or unsafe action, show the user:

• the exact write set and owner of every artifact;
• substantive generated sections and exact repository commands;
• setup, start, doctor, actions, observations, evidence, and cleanup;
• how the proposal satisfies the complete operational contract in references/generated-skill-contract.md, including every discovered enforcement mechanism and blocker;
• explicit isolated-port selection and how target identity and ownership will be verified;
• behavior claims each journey can and cannot prove;
• any new dependency, fixture, credential mechanism, process, port, data, or external side effect;
• which actions are safe to generate versus separately gated to execute.

Ask for explicit approval of that bounded proposal. Generator invocation is permission to inspect and propose, not blanket permission to modify the target project or drive it.

Complete when: the user has approved the exact durable writes and any separately scoped execution. Stop if a required file or action lies outside that approval.

4. Generate the smallest durable capability

Create or update the project-local SKILL.md and only necessary approved helpers. Use existing scripts, runners, fixtures, and tools where possible. Give tool-neutral roles alongside actual commands supported by the host and repository; never invent an interface or require one browser library everywhere.

Resolve helper paths from the generated skill directory. State the correct repository or monorepo working directory for every command. Apply references/generated-skill-contract.md as the source of truth for every operational requirement and blocker. Keep the artifact instructional: no new daemon, workflow database, control plane, or mandatory index.

Use references/examples.md only when a concrete browser, API, CLI, or blocked-case pattern would help shape the project-specific result.

Complete when: every approved file exists, the skill has one clear invocation/job, each journey has an observable completion contract, and every applicable operational step has an explicit finite budget enforced by a verified capability or is marked blocked.

5. Check the artifact

Run the repository's focused formatting, skill syntax, reference, or registration checks. Inspect the diff for unrelated changes and secrets. Check the artifact against the complete operational contract in references/generated-skill-contract.md. These checks prove that the artifact was generated and registered correctly; they do not prove a user journey.

Classify the result as:

• proposed — described but not written;
• generated — written and structurally checked;
• exercised — run against the authorized target with the required observations;
• blocked — a named requirement could not be proved, with the missing capability recorded.

Complete when: structural checks pass or their exact failures are reported, and the status does not overstate operational proof.

6. Exercise only authorized safe journeys

When the user separately approved execution, establish target identity and readiness before driving. Execute the generated skill under the complete operational contract in references/generated-skill-contract.md. Exercise the workflow on the real authorized surface and capture action plus resulting state plus required persisted effect. Use the generated contract's port-selection and owned-process receipt rules; store actual ephemeral runtime values only in the run receipt.

If authentication, a browser, infrastructure, target identity, or another required capability is unavailable, report blocked. Do not install replacements, weaken acceptance, or label the artifact tested. Preserve sanitized evidence after cleanup.

Complete when: an exercised claim has real observations at the named boundary and all bounded cleanup completed, or the precise timeout, cancellation, cleanup, capability, or other blocker and unverified claims are explicit.

7. Report

Return the generated paths, owner, journeys and supported surfaces, structural commands/results, exercise status, evidence locations, cleanup result, omissions, source provenance, and version uncertainty.

Complete when: another agent can distinguish what was proposed, generated, exercised, and blocked without inference.

Operational contract source

references/generated-skill-contract.md is the single source of truth for the complete generated artifact and execution contract. Apply it before proposing, generating, checking, exercising, or reporting operational instructions. When the target repository or host cannot satisfy one of its requirements, preserve the missing prerequisite and report execution as blocked.

Reference routing

Boundaries

test owns ordinary test creation, regression coverage, TDD, and executable test evidence. Browser or runner specialists own one-off interaction and tool syntax. This skill owns the distinct recurring job of creating or maintaining a repository-local verification skill and its approved helpers. Missing tests alone do not trigger this skill.