verifying-before-done skill (riekelt): prove it works before saying done

Makes Claude prove a change works by running it where a user meets it, and report exactly what it checked.

Installs: 20.3K; on skills.sh
Stars: 7; on GitHub
Updated: Sep 2026; last repo commit

verifying-before-done applies when Claude is about to say done, fixed, passing or shipped, or is reporting the outcome of a change. It asks Claude to run the smallest path that executes the changed code in the running system, run the verify command and paste its output, and report "PASS (checked X and Y)" instead of a bare checkmark. It also tells Claude to distrust a green suite until it has confirmed the test ran and can fail. It names principal-engineering as required background, and the plugin's change-verifier agent loads it.

Good for

Developers who are tired of "done" claims backed by a green suite alone
Reviewers who want the command and its output quoted
Teams that want an independent check on risky changes

Install verifying-before-done

Claude Code

Copy this prompt.

Install the verifying-before-done skill in Claude Code. Run this command:

/plugin marketplace add riekelt/principal-engineer
/plugin install principal-engineer@principal-engineer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The plugin installs all 11 skills in the repo, plus one agent (change-verifier) and two commands (/verify and /preflight), counted from the git tree. verifying-before-done names principal-engineering as required background, so the skills CLI and folder routes below install both. There is no Claude app upload route: the README documents only the Claude Code plugin and the other-agents routes.

From the project README. Source.

What's in the skill

When it loads

Use when about to say "done", "fixed", "passing", or "shipped", or when reporting the outcome of any change. Encodes verification as the definition of done: drive the change at its surface, run the verify command, report faithfully, distrust green suites, own failing gates. Use before every completion claim, even when the change was small and obviously correct, which is when this is skipped.

Sections in SKILL.md

Overview
The discipline
Verify at the surface
Failing gates you own
Common mistakes

Key facts

Author: riekelt (named as author in the plugin manifest)
License: MIT per the README and plugin.json; the repo has no LICENSE file and GitHub shows none
Installs on skills.sh: 20,310 (Nov 2, 2026)
GitHub stars: 7 for the whole riekelt/principal-engineer repo (Nov 2, 2026)
Last repo commit: Sep 11, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 1 file: SKILL.md (counted from the git tree)
Part of: The principal-engineer plugin: 11 skills, 1 agent and 2 commands (counted from the git tree)
Needs: The principal-engineering skill, named as required background in SKILL.md
Works in: Claude Code via the plugin; other agents via a plugin loader or symlinked skill folders, as the README describes

What it includes

Runs the smallest path that executes the changed code and captures output
The surface is where a caller meets the change: the command line, the endpoint, the screen or the import.
Runs code · Drive the change at its surface
Pastes the command output; "verified" always names what was checked
The command comes from the pre-change checkpoint. Secret values are redacted before output is quoted.
Runs code · Run the verify command
Reports failing tests with output and names skipped steps
Underclaiming verified work is called out as wasteful, the same as overclaiming.
Read · Report faithfully
Confirms a test ran and can fail by breaking the code and restoring it
A green suite over code that cannot work means the suite does not run, does not cover or cannot fail.
Runs code · Distrust green
Implemented is not deployed is not externally verified
Claude must not claim a later tier from evidence of an earlier one.
Read · Separate the tiers
Sweeps the diff for unrelated changes, residue and missing doc updates
Every acceptance criterion has to be met, not approximately met.
Read · Lookback before complete
Top-tier changes get a verifier who did not write the code
When none is reachable, the nearest substitute is used and named as the weaker form.
Read · Independent verification
Probes beside the change and never drives destructive paths live
Six rules, including at least one probe past the claim, quoting what the system produced and saying "no runtime surface" when none exists.
Runs code · Verify at the surface

From the official docs

Permissions

Low risk

verifying-before-done is instructions for Claude and the plugin route adds an agent and two commands. Our advice: review the diff after each session and keep your tool's permission prompts on.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Claude runs your code and may break it briefly
SKILL.md says to run the changed path and the verify command, and to break the code, watch the test go red, then unbreak it. Our advice: commit or stash your work before a verification run. github.com
The plugin route adds an agent that can run shell commands
change-verifier lists the tools Read, Glob, Grep and Bash, and the plugin adds the /verify and /preflight commands. The repo tree has no hooks or MCP config files. Use the skills CLI route to install only this skill. github.com

Technical details

Turning on read-only	SKILL.md describes no read-only mode.
Sign-in and keys	SKILL.md names no account, key or token.
Scopes	Claude runs your build, tests and the changed code path Claude may edit code temporarily to confirm a test can fail The plugin route also installs 10 other skills, one agent and two commands

Questions

What does verifying-before-done do?

It makes Claude treat "done" as a claim that needs evidence. Claude runs the changed code at its surface, runs the verify command, quotes the output, and names what it did not check.

How do I install it?

Use the install box at the top. The skills CLI and folder routes add principal-engineering as well, because this skill names it as required background. The plugin route installs all eleven skills and also adds the change-verifier agent and a /verify command.

How is it different from testing-changes?

testing-changes decides which tests a change owes. verifying-before-done covers proof at the moment of "done": driving the change at its surface and running the declared gates.

Is there an independent verifier?

In the plugin, yes. The README describes a change-verifier agent and a /verify command that dispatches it and relays VERIFIED, CONTRADICTED or UNVERIFIABLE unaltered. The agent's instructions say it verifies and reports and never fixes what it finds.

Does it work in the Claude app or Codex?

The README documents the Claude Code plugin and, for other agents, a plugin loader pointed at plugins/principal-engineer/ or symlinked skill folders. It documents no Claude app upload route.

Is it safe to install?

The skill folder bundles no scripts. It tells Claude to run your code, tests and checks, and to break code briefly to see a test fail. Commit or stash first. SKILL.md says never to drive destructive paths live.

Information

updated Nov 2, 2026

Repository: riekelt/principal-engineer
Folder: plugins/principal-engineer/skills/verifying-before-done

riekelt/principal-engineer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

verifying-before-done SKILL.md · github.com
principal-engineering SKILL.md · github.com
README · github.com
plugin.json · github.com
testing-changes file · github.com
change-verifier agent · github.com