README Generator

Generate human-focused README files following current best practices.

Core principle: README is for humans, not agents. Research → Analyze → Write.

Model recommendation: Use Task tool with model: haiku for README generation — faster and cheaper for documentation tasks.

When to Use

• Creating README for new project
• Rewriting outdated README
• User asks "write/create/update README"

Process

digraph readme_flow {
    rankdir=TB;
    "1. Research best practices via Exa" [shape=box];
    "2. Analyze project structure" [shape=box];
    "3. Identify project type" [shape=diamond];
    "4. Write README with appropriate sections" [shape=box];
    "5. Commit and push if requested" [shape=box];

    "1. Research best practices via Exa" -> "2. Analyze project structure";
    "2. Analyze project structure" -> "3. Identify project type";
    "3. Identify project type" -> "4. Write README with appropriate sections";
    "4. Write README with appropriate sections" -> "5. Commit and push if requested";
}

Step 1: Research

Always search first for current README best practices:

mcp__exa__web_search_exa: "best practices README.md {year} {project_type}"

Look for:

• Current trends in README structure
• Examples from similar projects
• What sections are essential vs optional

Step 2: Analyze Project

Read these files to understand the project:

• CLAUDE.md or existing docs
• package.json / pyproject.toml / Cargo.toml
• Main entry points
• Test files (understand features)

Step 3: Identify Project Type

Step 4: README Structure

Essential (all projects):

# Project Name

**One-line value proposition.**

Brief description (2-3 sentences max).

## What It Does / Features
- Bullet points of capabilities
- Focus on VALUE not implementation

## Quick Start
Minimal steps to get running (< 5 commands)

## Requirements
- Runtime versions
- System requirements
- Disk space if significant

## Usage
Examples for common cases

## Tech Stack (if non-trivial)
Table format preferred

## License

Optional by project type:

Writing Style

DO:

• Start with value, not implementation
• Use active voice
• Keep sentences short
• Include runnable examples
• Write for humans scanning quickly

DON'T:

• Include API reference for internal use
• Write walls of text
• Use jargon without explanation
• Include every possible option

Related Skills Section

If project has Claude Code skills, add:

## Related Skills

| Skill | Trigger | What it does |
|-------|---------|--------------|
| `skill-name` | "trigger phrase" | Brief description |

Quick Reference

Common Mistakes

Example Structure (Full-stack App)

# Project Name

**Value proposition in one line.**

Brief description.

## Features
- Feature 1
- Feature 2

## Quick Start
\`\`\`bash
./start.sh
\`\`\`

## Requirements
- OS/hardware
- Runtime versions

## Tech Stack
| Layer | Stack |
|-------|-------|

## Architecture
\`\`\`mermaid
flowchart...
\`\`\`

## Project Structure
\`\`\`
project/
├── ...
\`\`\`

## Related Skills
| Skill | Trigger | Description |

## Development
How to test, build

## License