The Art of README

A README is your project's front door. It's often the first thing people see, and it determines whether they stay or leave.

Philosophy

Bad READMEs: List features without context
Good READMEs: Tell a story—problem, solution, how to use

The best READMEs answer in 30 seconds:

1. What is this?
2. Why should I care?
3. How do I get started?

---

README Anatomy

Essential Sections

# Project Name

One-line description of what this does.

## Quick Start

Fastest path to "hello world"

## Installation

How to install/setup

## Usage

Basic examples

## License

What's allowed

Recommended Sections

## Features

What makes this special

## Documentation

Links to detailed docs

## Contributing

How to help

## Changelog

What's changed

Optional Sections

## Badges

Build status, coverage, version

## Demo

Screenshots, GIFs, live demo

## API Reference

For libraries

## FAQ

Common questions

## Acknowledgments

Credits, inspiration

---

Writing Each Section

Project Title & Description

# 🚀 ProjectName

> One sentence that explains the value proposition

A brief paragraph expanding on what this project does,
who it's for, and why it exists.

Rules:

• Lead with benefit, not features
• Keep it scannable
• Use emoji sparingly (or not at all)

Quick Start

## Quick Start

\`\`\`bash
npm install mypackage
\`\`\`

\`\`\`javascript
import { magic } from 'mypackage';

const result = magic('hello');
console.log(result); // 'HELLO!'
\`\`\`

Rules:

• 5 lines or less to first success
• Copy-pasteable commands
• Show immediate value

Installation

## Installation

### Requirements

- Node.js 18+
- PostgreSQL 14+

### Using npm

\`\`\`bash
npm install mypackage
\`\`\`

### Using yarn

\`\`\`bash
yarn add mypackage
\`\`\`

### From source

\`\`\`bash
git clone https://github.com/user/repo
cd repo
npm install
npm run build
\`\`\`

Rules:

• List prerequisites first
• Multiple installation methods if relevant
• Include environment setup if needed

Usage

## Usage

### Basic Example

\`\`\`javascript
// Describe what this example demonstrates
const result = doThing(input);
\`\`\`

### Advanced Usage

\`\`\`javascript
// More complex example with options
const result = doThing(input, {
  option1: true,
  option2: 'value'
});
\`\`\`

### Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| option1 | boolean | false | Does something |
| option2 | string | null | Does another thing |

Rules:

• Start simple, build complexity
• Real-world examples > contrived ones
• Tables for configuration

Features

## Features

- ⚡ **Fast** - Optimized for performance
- 🔒 **Secure** - Built with security in mind
- 📦 **Lightweight** - Minimal dependencies
- 🎨 **Customizable** - Extensive configuration options

Rules:

• Benefits > features
• Keep list short (5-7 items)
• Use consistent formatting

Contributing

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.

1. Fork the repository
2. Create your branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request

---

Badges

![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![Coverage](https://img.shields.io/codecov/c/github/user/repo)
![npm version](https://img.shields.io/npm/v/package)
![License](https://img.shields.io/github/license/user/repo)

Common badges:

• Build/CI status
• Test coverage
• Package version
• License
• Downloads
• Dependencies status

---

Process

1. Analyze the Project

# Check for existing docs
cat README.md
cat package.json
cat CONTRIBUTING.md

# Understand structure
ls -la
tree -L 2

# Check dependencies
cat package.json | grep dependencies

2. Gather Information

• Project name and purpose
• Installation requirements
• Main entry points
• Configuration options
• License

3. Generate README

Create or update README.md with all relevant sections.

---

Flags

• --minimal: Generate only essential sections
• --badges: Include badges section
• --contributing: Include detailed contributing guide

---

Output Location

• Creates README.md in project root if it doesn't exist
• If README.md exists, shows proposed changes for review

---

What NOT to Do

• ❌ Write a novel—be concise
• ❌ Assume context—explain acronyms
• ❌ Skip examples—show, don't just tell
• ❌ Leave outdated info—keep it current
• ❌ Ignore formatting—use headers, code blocks

---

Your Task

1. Analyze project structure and files
2. Read package.json, existing docs, config files
3. Identify key features and usage patterns
4. Generate comprehensive README.md
5. Create the file if it doesn't exist, or show changes if it does

Now generate README for: $ARGUMENTS