Index of every page on this site: llms.txt
All skills
Run it yourself

Proves a change works in the real running app before anyone says done - it starts the app, drives every flow the change touches the way a user or program would, compares the result with an answer key the builder did not write, and gets the verdict from a fresh agent, with evidence saved locally. On first use in a repo it sets up that repo's verifier (how to launch, check, drive and clean up the app, plus a feature map), and on branches the deliver skill marked, a global git pre-push hook blocks any push that was not proved. Works with any coding agent. Use when the user says prove it, verify this works, check it in the real app, show me it works, set up verification for this repo, "the agent keeps saying done without testing", when a push is blocked by "prove:", or before handing over or pushing any change. Not for writing test files - use testing; not for reviewing a diff - use `review`; not for a one-off browser task - use automation.

  • 8 files
  • 28.6 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/avik-creator/agent-skills/prove

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈239 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈4.1k more on demand in 4 files.

Description uses 12.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈958 characters, or 12.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Prove

"Done" means the change was seen working where users meet it, and checked against what right looks like. Code that compiles, passing tests, and the builder's reading of its own diff are not proof.

Quick start

  1. Turn on the global hooks: run <skill dir>/../_hooks/install, then install check, without asking. Tell the user in one line if it turned them on, or why they can't run in this repo (ship's hook.md covers hook managers). The hooks check only branches deliver marked (<git-common-dir>/deliver/<branch>). Why: the user wants the push checks for deliver work only.
  2. D=$(scripts/init) prints the .prove/ folder in the main checkout, creates it, and keeps it out of git.
  3. No $D/verifier.md: set it up first (setup.md).
  4. Find the task's keys in $D/keys/<task>/. None: build them with the user (answer-keys.md), then scripts/keys lock <task>. Run scripts/keys check <task>; a changed key is BLOCKED until the user approves it again.
  5. Scope, drive and get a verdict from a fresh agent (checker.md). Write the receipt, clean up, and report.

The folder (local only)

.prove/
  verifier.md         this repo's launch, doctor, drive, evidence and cleanup steps
  features/<name>.md  one file per user-facing feature
  scripts/            start, health, stop
  keys/<task>/        answer keys: plan.md, snapshots, expected outputs, locked checks
  locks/<task>.lock   fingerprints of the keys the user approved
  runs/<YYYYMMDD-HHMMSS>-<task>/  receipt.md, screenshots, logs

Why local: nothing from a real project leaves the machine, and teammates get no new folder.

Run

  1. Scope. From the diff, list what the change touches: new flows, and existing flows it reaches directly or through shared code (schema, auth, navigation, a shared component). Check only those. Why: checking the whole app is slow and hides what the change did. A change of new files only adds a short smoke test, keyed to the base commit.
  2. No runnable surface (docs, comments, CI config, types only): receipt with result NO-SURFACE and the reason, after a fresh agent (not script or self) reads the diff and agrees nothing runnable changed. Why: otherwise the builder could skip proof by saying there is nothing to prove.
  3. Launch and doctor as verifier.md says. If the app won't start, the flow is BLOCKED with the exact error. Why: no code change fixes a missing credential, so there is nothing to loop on.
  4. Scripts first: tests, API calls against saved responses, pixel diffs, stored-state counts. Why: a script gives the same answer every time and shares no blind spot with the builder.
  5. Drive each flow like a user, with methods.md. Capture the action, the resulting state and every side effect.
  6. Verdict from a fresh agent, as checker.md says. Route on the checker's verdict, never on the driver's claim.
  7. Receipt and cleanup: write runs/<run>/receipt.md as checker.md shows, stop only what this run started, then confirm the evidence is still there.

Verdicts

  • PROVED: every flow showed its pass signal, judged by a fresh agent or a locked script (never a pixel diff alone).
  • BROKEN: the app did something wrong. Report what, with evidence.
  • BLOCKED: the check couldn't run. Never put a weaker check in its place. Why: a weaker check that passes reads as proof.
  • UNPROVEN: no answer key, only the builder judged it, or a flow wasn't covered and the user didn't agree to that.

Rules

  • Only the user changes a key. A key that disagrees with the app goes to the user. Why: the builder must never set its own bar.
  • verifier.md changes only through the drift rule in setup.md, and each change is reported. The builder never loosens a check, edits the harness, or restructures code to pass. Why: each one turns a failure into a pass without fixing anything.
  • A check you have never seen fail proves nothing. Every new check catches a deliberately broken version once, as setup.md shows.
  • Don't trust a dry-run or test mode by its name; watch what it touches. Why: some still send email or call the network.
  • Real systems are off limits: no production data, real payments or real emails. Fake outside services and read the fake back.
  • Evidence uses made-up test data only. Why: a screenshot can end up in a PR.
  • BROKEN on work the user owns goes back to the builder: fix, prove again, at most 3 rounds, then stop and report. Why: a fourth try rarely works where three didn't. On someone else's change, report only.

The push gate

On a branch deliver marked, the global pre-push blocks a push unless the pushed commit has a receipt with result PROVED (with a named checker and a locked task whose keys still match, and no unagreed gaps) or result NO-SURFACE (with a fresh-agent checker). Every new commit needs a new run. PROVE_SKIP=1 skips one push; that is the user's call, never suggest it.

Example

User: "Prove the new invite flow." First run in the repo.

  1. Hooks on. No verifier.md: set it up (web plus API), and proved it catches a planted bug.
  2. Keys: the spec from the PR, and screenshots of the members page from the base commit. The user approved; locked as invite-flow.
  3. Scope: the invite flow (new), and the members page (shared component). The API check passed; a subagent judged both screens.
  4. Reply: "PROVED. Invite: spec (4), runs/20261103-142000-invite-flow/flow-1.txt. Members page: snapshot (2), 0% difference at 3 widths. Not covered: the invite email, because there is no local email catcher (agreed)."

Replies

Talk to the user in simple English: short sentences, everyday words, and a technical term only where it is needed, explained the first time it appears.

Lead with the overall result, then one line per flow: verdict, answer key and its rung, and the evidence path. Then what wasn't covered and why.

References

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at a0324a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 3 weeks ago

README badge

README badge for avik-creator/agent-skills/prove