README Writer

Write effective README files following SOTA 2026 best practices.

Quick Reference

| Section | Priority | Purpose | |---------|----------|---------| | Title + Tagline | Required | One sentence explaining what it does | | Badges | High | Build status, version, license at a glance | | Hero Example | Required | Copy-paste code that works immediately | | What It Does | Required | 3-5 bullets explaining value | | Quick Start | Required | Get running in under 10 minutes | | Why/Motivation | Medium | Problem-solution framing | | Features | Medium | Categorized feature list | | Installation | High | Step-by-step for different platforms | | Usage/Examples | High | Code examples with expected output | | API Reference | Medium | For libraries/CLIs with many commands | | Configuration | Medium | Config file locations and options | | Contributing | Medium | Link to CONTRIBUTING.md | | License | Required | Clear license statement | | ToC | High | For READMEs over 200 lines |

When to Use

Creating a new open source project
Improving an existing README that feels incomplete
Reviewing README quality before release
Converting internal docs to public README

Hero Pattern

The first thing users see should be:

Title: Project name
Tagline: One sentence (under 120 chars)
Badges: npm version, build status, license
Hero code: Runnable example in under 5 lines

# project-name

Brief tagline explaining what this does.

[![npm](https://img.shields.io/npm/v/project-name)](https://npmjs.com/package/project-name)
[![build](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)

\`\`\`bash
npx project-name init
\`\`\`

Decision Tree

How long is the README?

Under 100 lines: No ToC needed
100-200 lines: Optional ToC
Over 200 lines: ToC required

Is it a CLI tool?

Yes: Document --help, --json, show GIF demos
No: Focus on code examples

Is it a library?

Yes: API reference with types
No: Usage examples sufficient

Is it a monorepo?

Yes: Use monorepo-readme skill instead
No: Standard structure applies

Quality Checklist

Before publishing, verify:

[ ] New user can get running in under 10 minutes
[ ] Hero example works with copy-paste
[ ] All code examples are tested
[ ] No broken links
[ ] License is specified
[ ] Contact/contributing info exists

Reference Files

| Topic | File | |-------|------| | Section ordering | references/structure.md | | Badge patterns | references/badges.md | | CLI documentation | references/cli-docs.md | | Full checklist | references/checklist.md |

Skill Chaining

This skill works with:

markdown-writer: For consistent prose style
doc-maintenance: For keeping README updated
monorepo-readme: For multi-package projects

readme-writer