| name | readme-that-sells |
| category | write |
| description | Rewrite the README so a visitor gets it in ten seconds. What it does, why, how to run it, what works today. Use when they say "fix my README", "make my repo look good", or a project they want to show has a bare README. |
readme-that-sells
Rewrite a README with someone whose project deserves
better than the default one. The README is the landing page of
their work — recruiters, teachers, and other developers will judge
the project by it before reading a line of code. They write the
words; you know what a visitor needs and in what order. The
rewritten README is pushed by the end of the sitting.
Read the project first
Before touching the README, read the actual repo: what the code
does, how it runs, what state it is in. The README must match
reality. Then ask them the visitor questions and make them answer
out loud:
- What does this do, in one sentence a non-user understands?
- Why did you build it? The real reason — "my bus is always late"
is a better opening than any mission statement.
- What works today, and what is half-built or planned?
- How does someone run it on their machine, exactly?
Their spoken answers are the raw material. Write down what they
said, not what a README "should" sound like.
The 10-second test
Order matters more than polish. A visitor gives the page seconds:
- Name and the one-liner. Plain words. "Tracks the 42 bus in real
time" beats "A revolutionary transit solution."
- A screenshot, GIF, or live link if the project has a face. This
is the highest-value item on the page; help them capture one
now, not later.
- Why it exists — two or three sentences, their story.
- How to run it — commands they have actually re-run from a clean
clone in this session. A README whose install steps fail is
worse than no README.
- What's real: works / rough / planned, honestly labeled. Honest
scope reads as competence; a stranger can smell overclaiming.
Skip the badge wall, the empty "Contributing" boilerplate, the
license essay (one line and a LICENSE file is plenty), and any
section with nothing true to say.
Language pass
Go through their draft line by line. Cut every unverifiable
adjective — powerful, seamless, blazing, robust. Cut sentences
that describe no feature and make no claim a visitor can check.
Watch for machine-writing tells: triple lists for rhythm, "it's
not just a tracker, it's a platform" constructions. If the project
is small, the README should be short. Short and true is the goal.
Ship
- They run the install steps themselves from a fresh clone, top to
bottom. Fix the README (or the code) until the steps just work.
- Commit and push. Check how it renders on GitHub — formatting,
image, links.
- Send the repo link to one person who has never seen the project
and ask what they think it does. If the answer misses, the
one-liner gets another pass.
Done
- README states what the project does, shows proof, and labels current limitations
- Setup commands pass from a fresh clone on a documented environment
- Public rendering, media, and links are checked; an unfamiliar reader can state
the project's purpose accurately
If this project belongs on their resume, the build-resume skill
will want the one-liner they just wrote.
