/readme-reviewer

name: readme-reviewer
description: >
  Review a codebase and generate or update its README.md according to best practices.
  The skill performs static analysis of the project structure, dependencies, scripts,
  and existing documentation, then produces a comprehensive, accurate README.

  **Triggers — use this skill when:**
  - User asks to "review", "update", "improve", or "generate" a README
  - User says "create a README for this project"
  - User mentions "document this repo", "add documentation"
  - User asks to "fix my README" or "make my README better"
  - User provides a codebase and asks for documentation help

  **Covers:** Any project type — Node.js, Python, Rust, Go, Java, Ruby, PHP,
  monorepos, static sites, CLI tools, libraries, APIs, Docker-based projects,
  and more. Works with both new READMEs (from scratch) and existing ones (update/improve).

README Reviewer & Generator

Analyze a codebase and produce a high-quality README.md that follows industry best practices.

Philosophy

A README is the front door to a project. It should answer five questions in under 60 seconds:

1. **What** does this project do? 2. **Why** does it exist (and why should I care)? 3. **How** do I get it running? 4. **How** do I use it? 5. **How** can I contribute or get help?

Everything else is secondary. The skill prioritizes accuracy over boilerplate — every claim in the README must be verifiable from the codebase.

---

Workflow

Phase 1 — Deep Scan

Before writing a single line of the README, gather facts. Do NOT hallucinate features or commands. Every statement must come from the codebase.

# 1. Project structure overview
find . -maxdepth 3 -type f | head -80
ls -la

# 2. Package manifest & dependencies
cat package.json 2>/dev/null        # Node.js
cat Cargo.toml 2>/dev/null          # Rust
cat pyproject.toml setup.py setup.cfg requirements.txt 2>/dev/null  # Python
cat go.mod 2>/dev/null              # Go
cat Gemfile 2>/dev/null             # Ruby
cat composer.json 2>/dev/null       # PHP
cat pom.xml build.gradle 2>/dev/null  # Java/Kotlin

# 3. Available scripts & entry points
# Node: extract "scripts" from package.json
# Python: look for __main__.py, cli.py, manage.py, app.py
# Rust/Go: look for main.rs / main.go

# 4. Config files that reveal tooling
ls .github/workflows/ 2>/dev/null   # CI/CD
cat Dockerfile docker-compose.yml 2>/dev/null  # Docker
cat .env.example .env.sample 2>/dev/null       # Environment vars
cat Makefile 2>/dev/null            # Make targets
cat tsconfig.json 2>/dev/null       # TypeScript config
cat .eslintrc* .prettierrc* 2>/dev/null  # Linting

# 5. Existing documentation
cat README.md 2>/dev/null
cat CONTRIBUTING.md 2>/dev/null
cat LICENSE* 2>/dev/null
cat CHANGELOG.md 2>/dev/null
ls docs/ 2>/dev/null

# 6. Tests
ls tests/ test/ __tests__/ spec/ 2>/dev/null
grep -r "test" package.json 2>/dev/null | head -5

# 7. Git info (if available)
git remote -v 2>/dev/null
git log --oneline -5 2>/dev/null

**Extract from the scan:**

| Fact | Source | |------|--------| | Project name | Directory name, package manifest `name` field | | One-line description | Manifest `description`, or infer from code | | Language & runtime | File extensions, manifest, lock files | | Framework / major deps | Manifest dependencies | | Install command | Manifest scripts, Makefile, Dockerfile | | Run / start command | `scripts.start`, `scripts.dev`, entry point | | Test command | `scripts.test`, pytest, cargo test, etc. | | Build command | `scripts.build`, Makefile, Dockerfile | | Environment variables | `.env.example`, config files, code references | | CI/CD | `.github/workflows/`, `.gitlab-ci.yml`, etc. | | License | `LICENSE` file, manifest `license` field | | Existing docs quality | Current README completeness and accuracy |

Phase 2 — Assess (if updating existing README)

If a README already exists, evaluate it against the quality checklist (see below). Identify:

• **Missing sections** — required sections that don't exist
• **Stale information** — commands or versions that don't match the current codebase
• **Inaccurate claims** — features described that don't exist in code
• **Poor structure** — walls of text, missing headers, broken links
• **Missing quick-start** — no way for a newcomer to get running fast

Present findings to the user as a brief assessment before rewriting.

Phase 3 — Write / Rewrite

Generate the README using the structure below. Adapt sections to the project type — not every project needs every section. A 50-line CLI tool doesn't need an architecture diagram.

---

README Structure (Canonical Order)

Use this as the reference structure. Include sections that apply; skip those that don't.

1. Title & Badges (required)

# Project Name

[![License](badge-url)](license-url)
[![CI](badge-url)](ci-url)
[![Version](badge-url)](package-url)

• Project name as H1 — must match the repo/package name
• Badges: only include badges that are real and resolve (CI status, version, license, coverage)
• Do NOT invent badge URLs. Only add badges if you can determine the actual URLs from the CI config, package registry, etc.

2. One-liner / Tagline (required)

A single sentence (or short paragraph) explaining what this project does in plain language. No jargon. A non-technical person should understand the gist.

3. Key Features (if applicable)

A short bullet list (3–7 items) of what makes this project useful or unique. Only list features that actually exist in the codebase.

4. Quick Start (required for apps/tools)

The fastest path from zero to working. Should be copy-pasteable.

## Quick Start

\```bash
git clone <repo-url>
cd <project>
npm install
npm run dev
\```

• Use the actual commands from the project (verify they exist in package.json / Makefile / etc.)
• Include prerequisite versions if they matter (e.g., "Requires Node.js >= 18")
• If env vars are needed, show how to set them up

5. In