READMEs grounded in the actual codebase — 9 enforceable rules, benchmarked. Every published README skill we surveyed enforces structure or looks (templates, badges, hero images); none enforces truth. This skill's contract is different: a claimed feature must be found in source before it may be claimed, every command is copied from the project's real manifests and run — not pattern-completed from training data — and an honest limitations section is mandatory. The deliverable includes a verification log tracing each claim to file:line.
Built and bench-tested by SkillProof, the tested Claude skills directory.
This README was written under the skill's own rules: every claim below traces to SKILL.md or to the benchmark files in this repo, the install command was executed before publishing, and the limitations section is real.
We surveyed the README-writing landscape before building this (101 README-adjacent skills in a 16,682-skill catalog, plus readme-ai and the Standard Readme spec). The biggest dedicated README skill (2.2k★) is audience templates; the spec mandates section order but not working code blocks; the dominant CLI generator tells you to review its output for accuracy yourself. Three techniques showed up in none of them as enforceable rules — they are this skill's core:
- Fabrication ban with receipts. Every falsifiable claim is grepped in source first. Not found → not claimed. The verification log (
claim → file:line) ships with every README. - Commands copied, never composed. Install/run/test commands come from
package.jsonscripts, Makefiles, CI steps, or--helpoutput — and get executed in a clean checkout before they're documented. - Quickstart-to-first-success contract. The quickstart must take a new user from clone to one observable success (~60 seconds of instructions), every step executable exactly as written, ending in a checkable result.
Plus the rest: read-the-code-first inventory before drafting, fixed section order (what+why → install → quickstart → usage → config → limitations), a mandatory sourced limitations section, single-audience calibration, no badge/emoji inflation, and an audit-first mode for improving existing READMEs that removes stale claims before touching style.
git clone https://github.com/Skillproofdev/readme-discipline ~/.claude/skills/readme-discipline
# restart Claude Code — triggers on "write a README", "document this repo", README review requestsOne command — the repo IS the skill.
3–4 real small OSS repos without good READMEs, frozen at a commit SHA. Per repo: one baseline agent and one skill agent, identical model and prompt; the only difference is whether the agent reads this SKILL.md first. Scored on fabricated-claim count (every falsifiable claim audited against source with grep), command-executability rate (every documented command actually executed in a clean environment), section completeness, and blind developer preference with trust ratings. Full protocol: SkillProof methodology.
3 repos frozen at fixed SHAs — a Node CLI (crossplatform-killport), a Python CLI/library (python-shaarli-client), and a Flask web service (csrgenerator.com). Every command below was executed on a real machine; commands whose runtime was absent (Docker) or that need a live external service are excluded from the executability denominator and verified statically instead.
| Repo | Arm | Fabricated claims | Command-executability | Completeness /6 | Preferred | Trust /5 |
|---|---|---|---|---|---|---|
| crossplatform-killport | baseline | 0 | 8/8 (100%) | 5 | 4 | |
| crossplatform-killport | skill | 0 | 4/4 (100%) | 6 | ✓ | 5 |
| python-shaarli-client | baseline | 2 | 9/10 (90%) | 4 | 3 | |
| python-shaarli-client | skill | 0 | 7/7 (100%) | 6 | ✓ | 5 |
| csrgenerator.com | baseline | 0 | 3/6 (50%) | 5 | 4 | |
| csrgenerator.com | skill | 1 | 4/6 (67%) | 6 | ✓ | 4 |
| Aggregate | baseline | 2 | 20/24 (83%) | 14/18 | 0/3 | 3.67 |
| Aggregate | skill | 1 | 15/17 (88%) | 18/18 | 3/3 | 4.67 |
Across 3 repos the skill produced fewer fabricated claims (1 vs 2), higher command-executability
(88% vs 83%), complete sections every time (18/18 vs 14/18 — the baseline shipped no Limitations
section on any repo), and was preferred on all 3 with higher trust. The fabrication gap is narrow,
not a landslide: both baselines borrowed accurate content from the repos' existing docs, so the
baseline's misses were a stale Python 3.4+ requirement and two invented tox environments
(py34/py36) in the shaarli README — exactly the "claim traces to code, not to a project like this"
failures the skill exists to catch. The skill's own single slip (an "empty CN → HTTP 400" that is
actually 500) is logged honestly rather than hidden. Full audit trail, transcripts, and per-claim
file:line evidence: bench/ (see bench/results/verdict.md). Single-rater preference —
the ≥3-developer panel in the protocol was not run.
"Write a README", "create/rewrite README.md", "document this repo", "improve/review/audit this README", README generation during scaffolding or release prep. Explicitly excluded: full documentation sites (MkDocs/Docusaurus), API reference generation, changelogs.
- The command-execution rule (Rule 3) depends on the agent's environment being able to run the project; when it can't, commands are verified statically against manifests and flagged as unexecuted in the verification log — weaker than a real run.
- Grounding rules add reading work up front: on very large repos the code inventory costs tokens and time before the first word is drafted.
- The skill governs README.md files only; it will not structure a multi-page docs site.
- We publish negative results as-is — the table above is the measured outcome, caveats included.
We test other people's skills for a living (public methodology). Our own skills get the same treatment — measured benchmarks, negative results included.
More skills from us: skillproof-skills index · Free tools for skill authors: SKILL.md validator, token calculator, Rules⇄SKILL.md converter.
MIT — use it, fork it, ship it.