shown-work
Skill1 starsChanged 25 days agoMITView on GitHub
Treat done as a claim about reality and prove it against the real artifact before declaring it. Use when finishing any task or feature, before reporting success, when reviewing a claim that something works, or when a subagent or tool reports completion. Skip for throwaway exploration where nothing will be trusted.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- declared-breaksSkill
- deep-modulesSkill
- intakeSkill
- load-bearing-commentsSkill
- meaningful-testsSkill
- portable-skillsSkill
- verifySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Observe the real thing directly: Run the feature on the real path.
- Distinctive: line 19
Before declaring done, enumerate the claims "done" makes, and name the proof that pins each one.
- Distinctive: line 38
Every claim in "done" names its proof, and every proof has been run against the artifact rather than narrated.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Proven done
"Done" is a claim about reality, and reality does not accept self-reports. A task is done when the real artifact has been observed doing the real thing: the feature run, the actual value read back from the store, the file the change was supposed to write opened and looked at. "It compiles", "tests pass", and "should work" are proxies, and proxies are where silent breaks live.
The proof, not the assurance
- Observe the real thing directly. Run the feature on the real path; read the value out of the persisted store, not out of a variable; provoke the unhappy path on purpose (expired, revoked, duplicate, empty, legacy).
- Script the check when you can. A rerunnable proof script turns "trust me" into "run this". The script is the artifact a reviewer executes instead of believing you; keep its output with the claim, and commit it when the work will be trusted later.
- When a check fails, suspect the observation before the system. Half of false alarms are a measurement bug, and chasing the system first hides the real fault.
The gate
Before declaring done, enumerate the claims "done" makes, and name the proof that pins each one. A claim with no proof is not done; it is a hope with a deadline. Proxies that fail the gate:
- A count standing in for coverage ("15 checks green" says nothing about which behaviours the checks pin).
- A self-report, from a subagent, a tool, or your own earlier pass: implementers and reviewers alike misreport, so re-verify the claim against the artifact.
- Evidence from a stale run: a log, a screenshot, or a result from before the last change.
- "It should work" for anything on the unhappy path.
What counts as a proof
- The behaviour observed through the public interface, on the real path.
- The unhappy path provoked deliberately, with the actual error or outcome recorded.
- A rerunnable script whose output can be diffed by anyone with the repo.
Scale
One claim, one proof: for a single assertion mid-work ("the migration runs", "the export includes every row"), this gate is the whole procedure. A whole piece of work at its boundary, handed over or inherited, is the verify pass; do not run four moves on a one-line fix, and do not ship a feature on one proof.
Completion criterion
Every claim in "done" names its proof, and every proof has been run against the artifact rather than narrated. Zero claims rest on self-report.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

