GitHub README Generator

Writes READMEs by reading the actual project, not by interviewing the user about a project Claude could just look at. A README written from a code scan is more accurate and far faster to produce than one built from a user's verbal description, which tends to drift from what the code actually does.

Workflow

Step 1: Scan before asking

Before requesting any info from the user, gather what's inferable directly:

• package.json/pyproject.toml/Cargo.toml/etc. — name, dependencies, scripts (these reveal how to actually run/build/test the project)
• Entry point files (main.py, index.js, src/main.rs) — skim for what the program actually does on startup
• Folder structure — reveals architecture (monorepo? single service? is there a tests/ dir, a docs/ dir?)
• Existing README/docs, if any — don't discard prior content wholesale; preserve anything still accurate
• .env.example or config files — reveals required environment variables/setup steps
• CI config (.github/workflows/) — reveals the actual supported test/build commands, which is more reliable than guessing

Only ask the user for things genuinely not inferable from the repo: the project's purpose in plain language (code reveals what, rarely why), target audience, and license preference if none is set.

Step 2: Structure by project type

Not every README needs every section — pick based on what the repo actually is:

Library/package → Installation, Quick start (minimal working example), API reference (or link to it), Contributing Application/tool → What it does (one paragraph, no jargon), Screenshots/demo if visual, Setup, Usage, Configuration CLI tool → Installation, Usage (with actual command examples pulled from the code's arg parser, not invented ones) Portfolio/learning project → What it does, what it demonstrates (skills/concepts), how to run it, what you'd do differently with more time (this last part signals seniority and self-awareness — include it if the user seems to want a portfolio-quality result)

See references/section-templates.md for the full section-by-type breakdown.

Step 3: Write for skimmability, not completeness

A README is read in the first 30 seconds by someone deciding whether to keep looking. Front-load: what it is → why it matters → how to run it. Push deep API docs, architecture rationale, and contribution guidelines below the fold or into linked separate docs.

Step 4: Verify commands actually work as written

Every code block showing a command (npm install, pip install -r requirements.txt, a docker command) should match what's actually in the repo's config files — don't invent a script name that isn't in package.json's scripts field. If uncertain whether a command works, say so rather than presenting an unverified command as tested.

Step 5: Badges and metadata — only if they'll stay accurate

Build status / coverage / license badges are only worth adding if there's a real CI pipeline or published package to back them — a badge pointing at nothing looks worse than no badge.

Anti-patterns

• Generic "This project does X" filler paragraphs that could describe any project
• A giant unstructured feature list with no prioritization
• Copy-pasting a license section without confirming which license (if any) the user actually wants
• Writing installation instructions for a tech stack the code scan didn't actually find

Reference

• references/section-templates.md — full section templates by project type