Audit an existing README or generate one from scratch. Scores structure, clarity, install instructions, visual appeal. Makes open source projects professional.
--- name: readme description: Audit an existing README or generate one from scratch. Scores structure, clarity, install instructions, visual appeal. Makes open source projects professional. category: workflow tags: [readme, documentation, github, open-source, developer-experience] author: tushaarmehtaa --- Audit an existing README or generate one from scratch. Output is a README.md ready to commit. ## Phase 1: Determine Mode **Audit mode** — README.md exists in the project root. Score 8 dimensions, rewrite the weakest sections. **Generate mode** — no README.md, or user explicitly asks to write one from scratch. Gather anything missing before writing: - What does this project do? (one sentence a stranger would understand) - Who is it for? (specific audience, not "developers") - How do you install it? (exact commands) - How do you use it? (simplest possible example) If you can answer these by reading the codebase, do that instead of asking. ## Phase 2: The 8 Dimensions Score each 1–10 in audit mode. Use as a writing checklist in generate mode. **Name & Description (15%)** — Project name is clear. First paragraph explains what it does in plain language. A stranger can understand it in 5 seconds. **Visual Hook (10%)** — Logo, banner, screenshot, or GIF above the fold. Something visual that shows what the project looks like or does. No visual = automatic 1/10. **Badges (5%)** — Build status, version, license, download count. Use shields.io. Don't overdo it — 3-6 badges max. **Install (20%)** — Copy-pasteable commands. Covers npm/yarn/pnpm or equivalent. Prerequisites listed if any. Works on first try. **Usage (20%)** — Minimal working example. Shows expected output. A new user can go from install to "it works" in under 60 seconds. **API / Features (10%)** — Key features or API surface listed. Not exhaustive — just enough to know what's possible. Link to full docs if they exist. **Contributing (10%)** — How to set up the dev environment. How to run tests. Where to report bugs. Makes a first contribution feel approachable. **License (10%)** — License specified clearly. If missing, flag it — unlicensed code is legally unusable. ## Phase 3: Structure Rules The order that works. Don't rearrange without reason. ``` # Project Name [one-line description] [badges row] [screenshot / GIF / banner] ## Install [copy-paste commands] ## Usage [minimal example with expected output] ## Features [bullet list — benefit-first, not feature-first] ## API [if applicable — key methods/endpoints] ## Contributing [setup + test commands + link to issues] ## License [license name + link] ``` **Rules that don't move:** - **First paragraph is everything.** If someone reads nothing else, this paragraph must explain what the project does and who it's for. - **Install must be copy-pasteable.** No "configure your environment" hand-waving. Exact commands. - **Usage example must be minimal.** The simplest possible thing that shows it working. Not a full app — a 3-5 line snippet. - **Screenshot or GIF above the fold.** If the project has a UI, show it. If it's a CLI, show terminal output. If it's a library, show the code + output side by side. - **No wall of text.** Short paragraphs. Bullet points. Code blocks. A README is scanned, not read. - **Features lead with benefit.** "Generate OG images automatically" not "Dynamic Open Graph Image Generation Module." ## Phase 4: The One-Line Description The hardest part. One sentence under 15 words. **Formulas:** - "[Verb] [thing] [benefit]" — "Generate changelogs from git history" - "[Thing] that [does what]" — "CLI that audits your SEO in 30 seconds" - "[Outcome] for [audience]" — "Type-safe API routes for Next.js" **Test it:** paste the one-liner into a Slack message with no other context. Does the recipient understand what the project does? If not, rewrite. ## Phase 5: Badges Use shields.io. Pick from: ```markdown     ``` **3-6 badges.** More than that is noise. Order: build status, version, downloads, license. For non-npm projects, adapt: PyPI, crates.io, Go pkg, Docker pulls — whatever fits. ## Phase 6: Audit Output Format ``` README AUDIT — [project] ════════════════════════════════════ Name & Description [X/10] [one-line note] Visual Hook [X/10] [one-line note] Badges [X/10] [one-line note] Install [X/10] [one-line note] Usage [X/10] [one-line note] API / Features [X/10] [one-line note] Contributing [X/10] [one-line note] License [X/10] [one-line note] ──────────────────────────────────── Overall [X/80] ════════════════════════════════════ TOP 3 REWRITES: [Section]: [what's wrong] → [rewritten version] ``` ## Verify ``` [ ] One-line description under 15 words — a stranger gets it [ ] Screenshot, GIF, or banner visible above the fold [ ] Install commands copy-paste and work on first try [ ] Usage example is under 10 lines and shows expected output [ ] Features lead with benefit, not feature name [ ] No wall of text — short paragraphs, bullets, code blocks [ ] License specified [ ] Badges use shields.io with real endpoints [ ] README is under 300 lines — link to full docs for the rest [ ] Read it like a stranger — does it make you want to try this? ```
Creator's repository · tushaarmehtaa/tushar-skills