Working Writing skill
A README that sells
Rewrite the README so a visitor gets it in ten seconds.
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.
--- 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.