---

name: readme-craft description: Production-grade README.md patterns for any project type. Use when creating project documentation, writing README files, or improving existing docs. Covers hero sections, quick start examples, comparison tables, troubleshooting guides, and limitation transparency. Triggers on README, documentation, project setup, open source.

README Craft

Audience: Developers creating or improving project documentation.

Goal: Generate README files that convert scanners into users within 60 seconds.

Core Philosophy

A README is a sales pitch, onboarding guide, AND reference manual. Lead with value, prove with examples, document with precision.

Common Failures

Golden Structure

Tier 1: Hero Section

Copy<p align="center">
  <img src="logo.png" width="200" alt="Project Name">
</p>

<p align="center">
  <a href="..."><img src="https://img.shields.io/..." alt="CI"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="Version"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="License"></a>
</p>

<p align="center">
  <b>One-line description of what problem this solves</b>
</p>

```bash
curl -sSL https://example.com/install.sh | bash

Copy
### Tier 2: TL;DR

```markdown
## TL;DR

**Problem:** [Specific pain point users face]

**Solution:** [How this tool solves it]

| Feature | Benefit |
|---------|---------|
| Feature 1 | Quantified benefit |
| Feature 2 | Quantified benefit |
| Feature 3 | Quantified benefit |

Tier 3: Quick Example

Copy## Quick Start

# 1. Install
curl -sSL https://example.com/install.sh | bash

# 2. Initialize
mytool init

# 3. Run core workflow
mytool process input.txt --output result.json

# 4. Verify
mytool status

Rule: 5-10 commands demonstrating the core workflow.

Tier 4: Reference Sections

• Philosophy/Design decisions
• Alternatives comparison
• Installation (multiple methods)
• Command reference
• Configuration options
• Architecture (for complex systems)

Tier 5: Support Sections

• Troubleshooting
• Limitations
• FAQ
• Contributing
• License

Section Templates

Comparison Table

Copy## Why [Tool] Over Alternatives?

| Feature | [Tool] | Alternative A | Alternative B |
|---------|--------|---------------|---------------|
| Speed | 50ms | 200ms | 150ms |
| Memory | 10MB | 50MB | 30MB |
| Feature X | Yes | No | Partial |
| Feature Y | Yes | Yes | No |

**Choose [Tool] when:** [specific use case]
**Choose Alternative A when:** [specific use case]

Installation (Multiple Methods)

Copy## Installation

### Quick Install (Recommended)

```bash
curl -sSL https://example.com/install.sh | bash

Package Managers

Copy# macOS
brew install mytool

# Linux
apt install mytool  # Debian/Ubuntu
dnf install mytool  # Fedora

# Windows
winget install mytool

From Source

Copygit clone https://github.com/user/mytool
cd mytool
make install

Copy
### Command Reference

```markdown
## Commands

### Global Flags

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Increase output verbosity |
| `-q, --quiet` | Suppress non-error output |
| `--config PATH` | Use custom config file |

### `mytool init`

Initialize a new project.

```bash
mytool init                    # Interactive setup
mytool init --template minimal # Use template
mytool init --force            # Overwrite existing

mytool run

Execute the main workflow.

Copymytool run input.txt           # Basic usage
mytool run -o output.json      # Custom output
mytool run --dry-run           # Preview changes

Copy
### Troubleshooting

```markdown
## Troubleshooting

### Error: "Permission denied"

**Cause:** Installation script lacks execute permissions.

**Fix:**
```bash
chmod +x install.sh
./install.sh

Error: "Command not found"

Cause: Binary not in PATH.

Fix:

Copyexport PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence

Error: "Config file not found"

Cause: Missing configuration.

Fix:

Copymytool init --config

Copy
### Limitations

```markdown
## Limitations

**Current constraints:**

| Limitation | Workaround | Planned Fix |
|------------|------------|-------------|
| Max 10MB files | Split large files | v2.0 |
| No Windows GUI | Use WSL | Under review |
| Single-threaded | Use multiple instances | v1.5 |

**Out of scope:**
- Feature X (use [Alternative] instead)
- Feature Y (not planned)

FAQ

Copy## FAQ

<details>
<summary><b>Q: How does this compare to [Alternative]?</b></summary>

[Tool] focuses on [specific strength], while [Alternative] excels at [different use case]. Choose [Tool] when you need [criteria].

</details>

<details>
<summary><b>Q: Can I use this in production?</b></summary>

Yes. [Tool] is used in production by [companies/projects]. See our [stability policy](link).

</details>

Badge Reference

Copy<!-- CI Status -->
![CI](https://github.com/USER/REPO/actions/workflows/ci.yml/badge.svg)

<!-- Version -->
![Version](https://img.shields.io/github/v/release/USER/REPO)

<!-- License -->
![License](https://img.shields.io/badge/license-MIT-blue)

<!-- Downloads -->
![Downloads](https://img.shields.io/github/downloads/USER/REPO/total)

<!-- Package Managers -->
![npm](https://img.shields.io/npm/v/PACKAGE)
![PyPI](https://img.shields.io/pypi/v/PACKAGE)
![Crates.io](https://img.shields.io/crates/v/PACKAGE)
![Gem](https://img.shields.io/gem/v/PACKAGE)

Progressive Disclosure

For long READMEs (1000+ lines):

Copy<details>
<summary><b>Advanced Configuration</b></summary>

[Detailed content here]

</details>

Or externalize:

• docs/CONFIGURATION.md
• docs/ARCHITECTURE.md
• docs/CONTRIBUTING.md

Keep README focused on the 80% use case.

Pre-Publication Checklist

Hero:

• Logo/image present
• Badges current and working
• One-liner describes the problem solved
• Quick install command visible

Content:

• TL;DR within first scroll
• Every feature has an example
• Code blocks are copy-paste ready
• 3+ installation methods documented

Trust:

• Comparison with alternatives (honest)
• Limitations documented
• Top 5 errors in troubleshooting
• All links verified

Polish:

• Consistent terminology
• No stale badges
• Grammar/spelling checked

Anti-Patterns

Reference Examples

Study these for excellent README patterns:

• ripgrep - Benchmark data, comparison matrices
• bat - Feature highlights, visual demos
• starship - Configuration presets, install matrix
• jq - Tutorial progression, manual linking