Agent skill and instructions

Teach your agent the verifAIed loop once, so it uploads, checks and fixes without you asking each time.

Install the skill

The CLI ships a skill that teaches an agent the whole loop: the commands, when to stop, and what it must never do to make a check pass, such as lowering a threshold or skipping a failing test. Run this in your repository:

verifaied skill install

It writes the skill to .claude/skills/verifaied in the repository, where a Claude Code agent reads it on its next session. Commit it so everyone working on the repository gets it.

  • --user installs it for every repository on your machine instead.
  • --force replaces an installed copy that differs. Run it after you upgrade the CLI to update the skill.

The skill comes with the CLI, so it always matches the commands your version has. With Claude Code, verifaied setup claude installs it for you; see Set up.

Rules to paste

If your agent reads an instructions file instead of a skill, such as CLAUDE.md, AGENTS.md or .cursorrules, paste these rules into it. Each one stands on its own. Start with the first and add the others as you start using what they cover.

The one-paragraph rule
The smallest thing that works. Paste this and your agent stops guessing when it is done.
After you implement a feature, run the test suite with coverage and upload the
report:

    verifaied upload

Then ask whether the work is finished — the check_done MCP tool, or
`verifaied check-done` from the terminal. While it reports gaps, close them and
ask again: call the fix_branch MCP tool for one LLM-written prompt covering
every gap on the branch, or get_baseline_prompt(function_id) for a free prompt
per function. Stop when check_done answers done: true — not before, and not
because the tests happen to be green.

For how any part of verifAIed works, call the docs MCP tool and answer from
what it returns.
The full coverage loop
The same loop spelled out, with the coverage commands for Python and TS/JS.
## Test-coverage loop (run until done)

1. Run tests with coverage:
   Python:  pytest --cov --cov-branch --cov-context=test --junitxml=junit.xml
            coverage json --show-contexts -o coverage.json
   TS/JS:   vitest run --coverage --coverage.provider=istanbul --coverage.reporter=json \
              --reporter=junit --outputFile.junit=junit.xml
2. Push the results:   verifaied upload   (or the upload_local_coverage MCP tool)
3. Ask if you're done: verifaied check-done   (or the check_done MCP tool)
4. If done is true, stop — the branch is covered.
   Otherwise, fix each gap in the output — call get_baseline_prompt(function_id)
   for a free test prompt, or fix_branch for an LLM-written one — then go to 1.
Prove anything a person can click
Have the agent record a browser test for the flow it just changed, and commit the spec.
## Browser tests (anything a person can see or click)

When a change adds or alters a route, a page, a form field or a clickable
surface, record a browser test for the flow before you call the work done.

Register `verifaied test mcp` as an MCP server named verifaied-recorder and
drive the app yourself: start_recording, then run_steps in small batches
against the refs the page snapshot hands back, then finish_recording. The
spec it saves lands under .verifaied/tests/ — commit it with the change it
proves.

No MCP server on this machine? Record the same flow from the terminal:

    verifaied test record "<Feature>/<what the flow does>"

Replay everything already recorded with `verifaied test run --all`. A recorded
test that has not passed on this branch is an unverified_recorded_test gap in
check_done, so this is part of finishing the work rather than an extra.
Check the UI you changed
A screenshot judged against what the change was for, and a free deterministic audit under it.
## Check the UI you changed

After a visual change, screenshot the running page and ask whether it does what
you meant — the verify_ui MCP tool:

    verify_ui(repository="<owner>/<repo>",
              intent="The error state shows a Retry button under the message",
              target="src/components/ErrorPanel.tsx::ErrorPanel",
              screenshot_base64=<base64 PNG>)

It answers pass, fail or unclear. Treat unclear as "capture the right region and
ask again" — never as a pass. Drop the intent and you get a rubric audit instead.

For the free, deterministic half — anything spilling out of the viewport, text
below the WCAG AA contrast minimum, images that failed to load, errors the
console logged — run the audit. No model, no cost:

    verifaied audit http://localhost:5173

Definition of done explains the answer the rules tell the agent to wait for.

Let the loop run unattended

The agent calls verifAIed tools on every pass through the loop. If it has to ask you for permission each time, the loop stops and waits for you. Approve the verifAIed tools once:

  • In Claude Code, when it asks the first time, choose the option that does not ask again for verifaied tools. To approve before the first call, run /permissions and add mcp__verifaied to the allow list. That covers every tool the server has.
  • In another agent, find its tool approval setting and mark the verifaied server as always allow.