---
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:

1. Name and the one-liner. Plain words. "Tracks the 42 bus in real
   time" beats "A revolutionary transit solution."
2. 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.
3. Why it exists — two or three sentences, their story.
4. 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.
5. 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.