# Github Readme Generator

> Generate or overhaul a GitHub repository README by actually reading the codebase (package.json, entry points, existing docs, folder structure) rather than asking the user to describe their own project. Use whenever the user asks to "write a README", "document this repo", "improve my README", shares a repo/folder and wants documentation, or is about to open-source/publish a project and needs a portfolio-quality README. Also trigger when a repo is shared with no README at all and the user's goal involves sharing or publishing it.

- Skill: `zeiynz/github-readme-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zeiynz/github-readme-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeiynz/github-readme-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zeiynz (https://skillmd.com/u/zeiynz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeiynz/github-readme-generator

---


# 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