Skills / A README that sells
A README that sells
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.
Use this skill. Nothing to install.
Don't have an agent? · Raw file: skills/readme-that-sells.md
Watch the first two minutes
This is how a session goes, starting from the README everyone actually has. Click through it.
Scripted example of a real session.
Is my project even big enough to deserve a README?
If a stranger might ever see the repo, yes. Recruiters, teachers, and other developers judge the project by its README before reading a line of code, and a small project with a short, true README reads as competence. The skill sizes the page to the project: if the project is small, the README is short. What it never does is inflate; honest scope is the selling point, because a stranger can smell overclaiming. No repo yet? Any of these gives you one worth writing up.
What you end up with
A README a visitor gets in ten seconds, pushed before the session ends. Same project, before and after.
# my project A comprehensive platform for real-time transit data visualization and analysis. ## Installation TODO
# bus42
Shows where the 42 bus actually is right now, so you
know if you can still make it to the stop.
I built this because the posted schedule at my stop
is wrong more often than it is right.
## Run it
git clone https://github.com/mayatorres/bus42
cd bus42 && npm install
cp .env.example .env # add a free transit API key
npm start
## What's real
- Works: live position for line 42, arrival guess
- Rough: arrival guess is off at rush hour
- Planned: any line, not just mine- The before overclaims and under-delivers. "Comprehensive platform" describes nothing a visitor can check, and "Installation: TODO" tells them the author gave up. This combination is the default state of most student repos, which is exactly why fixing it stands out.
- The after answers the visitor's questions in order. What it does in plain words, a GIF that proves it, why it exists in the author's real voice, install steps that were re-run from a clean clone in the session, and an honest works / rough / planned list. No badge wall, no boilerplate Contributing section, no license essay.
Anatomy of the one-liner
The first sentence under the project name decides whether anyone scrolls. The skill builds it to this shape:
- A What it does, with a verb a friend would use. Scope stated honestly: one bus line, and that's fine.
- B Why a person would want that, concretely. This clause is where "platform for visualization" goes to die.
Questions people actually ask
Is this free?
The skill is free, no account, no catch. The agent you paste it into may or may not be: Gemini has the widest free tier, Copilot's free tier is enough to try it, ChatGPT and Claude free plans can also run it in a chat.
Will my README sound like AI wrote it?
The language pass exists to prevent exactly that. Unverifiable adjectives like "powerful", "seamless", and "blazing" get cut, along with rhythmic feature lists and "it's a platform" inflation. The why-it-exists section is your story in your words, and the agent writes down what you said, so the page keeps your voice.
Does it work if my project is half-finished?
Yes, and it says so on the page instead of hiding it. The works / rough / planned section is part of the format because honest scope reads as competence. What the skill won't do is describe features that don't exist yet as if they do.
What if my install steps don't work?
That's usually discovered mid-session, because you re-run them yourself from a fresh clone before shipping. Then you fix the README, or the code, until the steps just work. This step is the single most common thing the skill catches.
How do I know the new README lands?
The skill ends with a real test: send the repo link to one person who has never seen the project and ask what they think it does. If their answer misses, the one-liner gets another pass. Checking how it renders on GitHub, image and links included, is part of shipping.
Where to go from here
README pushed? Put the repo to work:
Want the repo itself in better shape?
Curious? Read the full skill — the exact instructions your agent gets
--- 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.