zeiynz 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, adocs/dir?) - Existing README/docs, if any — don't discard prior content wholesale; preserve anything still accurate
.env.exampleor 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