Readme Refresher

The readme is the front door of a repository, and front doors rot: setup steps drift from reality, badges point at dead pipelines, examples show an API two majors old. This skill audits an existing readme against the repository as it is today, then rewrites the smallest set of sections needed to make a newcomer succeed on their first attempt. It is a maintenance skill — the goal is accuracy and onboarding speed, not prose beauty.

When to use this skill

• Setup instructions failed for a new contributor or on a fresh machine
• The project changed shape (new build tool, renamed commands, moved directories) since the readme was last touched
• Preparing a repository to go public or be handed to another team
• The user asks to "update", "fix", or "modernize" the readme

Workflow

1. Audit before writing. Read the readme top to bottom and mark every checkable claim: install commands, version requirements, file paths, example invocations, links. Build a claim inventory.
2. Verify each claim against the repository, not against plausibility. Do the paths exist? Do the scripts named in the readme appear in the manifest or task-runner config? Does the quick-start command match what the test pipeline actually runs? Where possible, execute the setup steps in order and record where they first fail.
3. Classify each claim: correct, stale (was true, is not), or aspirational (never was true). Aspirational claims get deleted, not repaired — a readme is documentation, not a roadmap.
4. Fix the critical path first, in this order: what the project is (two sentences, no adjectives), prerequisites with exact versions, install, the one command that proves it works, and where to go next. A newcomer should reach a visible success inside those five sections.
5. Trim what does not serve a newcomer. Move deep configuration reference, architecture essays, and changelog fragments into linked docs. The readme keeps a table-of-contents role for anything it evicts.
6. Re-run the final quick start from a clean state if the environment allows it. The refreshed readme must be transcript-accurate: every command copy-pasteable, expected output shown wherever ambiguity exists.
7. Report the delta: claims fixed, claims deleted, sections moved — so the change reads as an audit, not a mystery rewrite.

Output format

Deliver two things: the updated readme content, and an audit summary shaped like this:

Verified: 14 claims
Fixed:     5 (install cmd, minimum runtime version, 2 paths, test command)
Deleted:   2 aspirational (plugin system "coming soon" for two years)
Moved:     config reference -> docs/configuration.md
Unverifiable here: publish step (needs registry credentials) — flagged inline

Quality bar

• Every command in the readme either ran successfully during the refresh or is explicitly flagged as unverified, with the reason. No silent trust.
• Version numbers appear once, in prerequisites — not scattered and disagreeing across sections.
• The first screen of the readme answers: what is this, who is it for, how do I see it work.
• No marketing voice. "Fast" and "simple" are judgments that belong to users, not assertions that belong to maintainers.
• The diff stays minimal outside the sections that needed repair; a refresh that reflows every paragraph destroys blame history for zero reader benefit.

Refresh checklist

• Claim inventory built and each claim verified, not skimmed
• Install and quick-start executed from a clean state, or flagged
• Aspirational content deleted rather than softened
• Critical path (what / prerequisites / install / prove it / next) intact and ordered
• Audit summary delivered alongside the rewrite