serejaris/readme-generator

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

| Type | Key Sections | |------|--------------| | CLI Tool | Usage examples, Options table, Installation | | Library/SDK | API overview, Quick start, Examples | | Web App | Features, Quick start, Architecture diagram | | Full-stack | Architecture, Quick start both parts, Tech stack | | AI/ML | Model info, Requirements (GPU), Examples |

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:

| Section | When to Include | |---------|-----------------| | Architecture diagram | Web apps, full-stack, complex systems | | Project Structure | Open source, contribution expected | | API Reference | Libraries, SDKs (or link to docs) | | Related Skills | If Claude Code skills exist | | CLI Options table | CLI tools | | Configuration | Apps with config files | | Known Limitations | If significant gotchas exist |

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

| Project has... | Include | |----------------|---------| | Web UI | Screenshot or architecture | | CLI | Options table, examples | | API | Endpoint summary (not full docs) | | AI/ML | Model, hardware requirements | | Claude skills | Related Skills table | | Complex arch | Mermaid diagram |

Common Mistakes

| Mistake | Fix | |---------|-----| | API docs dump | Link to separate file or remove | | No quick start | Add "clone → run" in < 5 steps | | Wall of text | Use bullets, tables, code blocks | | Missing requirements | Always list runtime + system reqs | | Generic description | Start with specific value prop |

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