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.
[](https://npmjs.com/package/project-name)
[](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-readmeskill 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