readme-reviewer

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