README Update Skill: Reality Check the Docs
The worst README is the one that's confidently wrong. A new contributor clones the repo, follows the setup steps, hits the second command, sees an error, and concludes the project is broken. This skill checks every claim against the actual repo before writing.
An installable README-update skill. Checks every claim in the README against the actual repo — setup commands, versions, env vars, file paths — and fills the gaps a new contributor would hit.
What It Does
- Verifies every command —
npm install,make setup, everynpm run Xmentioned - Verifies every version — checks
.nvmrc,engines,runtime.txtagainst what's claimed - Verifies every env var — bidirectional check: code → docs and docs → code
- Verifies every file path — does
src/api/still exist where the README says?
Install in 30 Seconds
Pick your tool above and download:
- Claude Code:
~/.claude/skills/readme-update/SKILL.md - OpenAI Codex CLI: append to
AGENTS.md - Cursor: append to
.cursorrules
Run once after a refactor lands, or quarterly as a maintenance pass.
Why Stale Docs Cost More Than Missing Ones
Missing docs make a contributor ask in chat. Stale docs make a contributor follow the instructions, fail silently, and lose an hour before realizing the README is the problem. The trust cost compounds: once someone catches the README in a lie, they stop trusting any of it. This skill closes the gap with a verification pass first, prose second.
Install once, run it before the next contributor lands.