"Done" is a claim. An agent that reports a task finished and an agent that shows you the test failing, then the same test passing after the change, are doing two different things. Most teams accept the first and then spend their review time trying to work out whether the second happened.
This post is about a small artefact that closes that gap: a Claude Code skill whose only job is to make the agent produce evidence before it is allowed to say it is finished.
What the skill is, in one paragraph
A skill is a markdown file with frontmatter that lives in the repository, under .claude/skills/. Claude Code loads it when the description matches what is happening, without anyone remembering to mention it. This one triggers at the end of a task and turns the completion report into a fixed shape: task type, commands run, real output pasted, files touched, and an explicit list of what was not verified.
It is deliberately boring. The value is not clever prompting. It is that the shape is the same every time, so a reviewer knows within five seconds whether there is anything to trust.
What does a Claude Code verification skill actually check?
It checks that a completion claim arrives with artefacts rather than adjectives. The skill requires the agent to classify the work first, run the command that would prove the change behaves as described, paste the actual output rather than a summary of it, list every file it touched, and state plainly what it could not check. Anything without evidence gets reported as unverified rather than as done, which is the whole point.
The evidence pack, by type of change
Different work needs different proof, so the skill branches on the task type the agent declares. The table sets out what we require on client repositories. Replace the commands with your own before you use it.
| Change type | Required artefact | What it rules out |
|---|---|---|
| Bug fix | The new test failing before the change and passing after, both runs pasted | A fix for a bug that was never reproduced |
| New feature | Test run for the new path plus the full suite result | A feature that quietly breaks something else |
| Refactor | Test output from before and after, identical | A behaviour change smuggled into a tidy-up |
| Dependency change | Install log, lock file diff and a clean build | A version bump nobody actually resolved |
| Database migration | Up and down run against a copy, with row counts either side | An irreversible change discovered in production |
| Documentation only | The file list, and nothing under a source directory | Code changes hidden inside a docs commit |
The last row earns its place more often than people expect. A docs-only claim with a source file in the diff is the cheapest red flag you will ever catch.
What goes in the file
The skill is short, five sections, and you can write it in half an hour. Keep the language concrete, because a skill written in generalities produces generalities.
Frontmatter: a name and a description that says when it applies, worded around the moment a task is about to be reported complete.
A classification step. The agent names the task type before it verifies anything, because the type decides what proof is required.
A command list per type. Write the actual commands from your repository, not "run the tests". An agent that has to guess the command will guess the evidence too.
An output block. The agent pastes raw command output. Summarised output is not evidence, it is the agent's opinion of evidence.
An unverified section. The agent lists what it could not check and why. This is the part reviewers should read first, and it is the section most teams leave out.
That unverified section changes behaviour more than the rest of the file combined. Given somewhere honest to put uncertainty, an agent will use it instead of papering over it.
Why a skill and not a line in CLAUDE.md
CLAUDE.md is loaded at the start of every session and is the right home for standing facts about the codebase. A verification routine is a multi-step procedure that only matters at one moment in a task, which is exactly the shape Anthropic's documentation says to move out of CLAUDE.md and into a skill. Putting it in CLAUDE.md spends context on every task to change behaviour on some of them.
It is worth being clear about what a skill is and is not. Like CLAUDE.md, a skill is instruction rather than enforcement. If you need a hard gate, a PreToolUse hook that refuses a commit without attached test output is the mechanism. We compared the options in 7 ways to steer Claude Code. In practice most teams want both: the skill produces the evidence, the hook makes it non-optional on the branches that matter.
What this skill does not do
Four honest limits, because a verification artefact invites more confidence than it earns.
It cannot tell you the requirement was right. An agent can prove it built exactly the wrong thing.
It does not replace human review on high-risk changes. Evidence makes a change faster to review, not safe to skip.
Evidence can be selective. Require the full suite result alongside the new test, or you will get the one run that looks good.
It is only as strong as the test suite behind it. On a thinly tested path, a green run proves very little and the skill will happily say so if you keep the unverified section.
That last point is the reason we usually look at coverage on the changed paths before rolling this out. A verification habit built on a weak suite manufactures confidence, which is worse than having none.
What it saves an Australian team
The saving is not dramatic per change. It is that a recurring conversation disappears. On a six-person Sydney team where each reviewer spends half an hour a day working out whether the agent actually ran anything, that is roughly 660 hours a year. At an indicative fully loaded rate of $110 an hour, about $72,000 of senior time a year goes to a question a five-line markdown file answers automatically. Those are planning figures rather than a quote.
The larger effect is on what reviewers do with the time. Attention moves from reconstructing what the agent did to judging whether it should have been done, which is the part a person is genuinely better at.
Building your own version
Start with one task type. Bug fixes are the easiest, because the proof is unambiguous: a test that fails before and passes after. Write that branch, use it for a week, then add the next type when the first one has stopped surprising you. A skill covering two types well beats one covering six speculatively.
If you want help writing the first version against your own build commands, our services page covers how we scope it, and the reference for skill structure is Anthropic's Claude Code documentation. For a wider look at where agents pay for themselves, our ROI calculator uses the same inputs as the figures above.
If your team is still taking the agent's word for it, that is worth half an hour of someone's time to fix. Book a conversation and we will walk through what evidence your repository can actually produce today.
