readme-writing

name	readme-writing
description	Craft professional README.md files for GitHub open source projects. Generates hero sections, installation instructions, feature tables, and architecture diagrams. Use when creating or revising a README, documenting a CLI tool, library, or open source project, or when user asks about README structure, badges, or project documentation.

Crafting README.md Files for GitHub

Core insight: A README is a sales pitch, onboarding guide, and reference manual compressed into one document. Lead with value, prove with examples, document with precision.

The One Rule

Great READMEs convert scanners into users in under 60 seconds.

Most fail because they:

• Bury the value proposition under installation steps
• Explain what the tool IS instead of what problem it SOLVES
• Lack concrete examples (abstract descriptions don't sell)
• Miss the "quick escape hatch" for impatient users (curl one-liner)
• Don't show how it compares to alternatives

---

Fast Track: README in 5 Minutes

1. Read existing README (if any)
2. Run THE EXACT PROMPT below
3. Run Pre-Publish Checklist
4. Ship it

---

THE EXACT PROMPT

Read the current README.md and dramatically revise it following this structure:

1. Hero section: illustration + badges + one-liner description + curl install
2. TL;DR: "The Problem" + "The Solution" + "Why Use X?" feature table
3. Quick example showing the tool in action (5-10 commands)
4. Design philosophy (3-5 principles with explanations)
5. Comparison table vs alternatives
6. Installation (curl one-liner, package managers, from source)
7. Quick start (numbered steps, copy-paste ready)
8. Command reference (every command with examples)
9. Configuration (full config file example with comments)
10. Architecture diagram (ASCII art showing data flow)
11. Troubleshooting (common errors with fixes)
12. Limitations (honest about what it doesn't do)
13. FAQ (anticipate user questions)
14. About Contributions (use EXACT policy text from skill)

Make it comprehensive but scannable. Use tables for comparisons.
Show, don't tell. Every claim should have a concrete example.
Use ultrathink.

---

Golden Structure

1. HERO SECTION (above the fold)
   ├─ Illustration/logo (centered)
   ├─ Badges (CI, license, version)
   ├─ One-liner description
   └─ Quick install (curl | bash)

2. TL;DR (sell the value)
   ├─ The Problem (pain point)
   ├─ The Solution (what this does)
   └─ Why Use X? (feature table)

3. QUICK EXAMPLE (prove it works)
   └─ 5-10 commands showing core workflow

4. REFERENCE SECTIONS
   ├─ Design Philosophy
   ├─ Comparison vs Alternatives
   ├─ Installation (multiple paths)
   ├─ Quick Start
   ├─ Commands
   ├─ Configuration
   └─ Architecture

5. SUPPORT SECTIONS
   ├─ Troubleshooting
   ├─ Limitations
   ├─ FAQ
   ├─ About Contributions (MANDATORY - use EXACT text below)
   └─ License

---

Critical Rules

#	Rule	Why
1	Lead with value, not installation	TL;DR before Quick Start
2	Curl one-liner above the fold	Impatient users escape hatch
3	Every feature claim needs an example	Show, don't tell
4	Comparison tables beat prose	Scannable > readable
5	Be honest about limitations	Builds trust, saves support time
6	Multiple installation paths	curl + package manager + source
7	Architecture diagrams for complex tools	ASCII art is fine
8	Troubleshooting section is mandatory	Top 5 errors with fixes

---

Contributions Section (MANDATORY)

Always include this EXACT text in every README:

About Contributions: Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

---

Pre-Publish Checklist

□ Hero section with illustration + badges + one-liner + curl install
□ TL;DR with Problem/Solution/Feature table
□ Quick example (5-10 commands)
□ At least 3 installation methods documented
□ Every command has usage examples
□ Architecture diagram for complex tools
□ Comparison table vs at least 2 alternatives
□ Troubleshooting section (top 5 errors)
□ Honest Limitations section
□ FAQ with 5+ questions
□ "About Contributions" section with EXACT policy text
□ All code blocks are copy-paste ready
□ No broken links or badges
□ Consistent terminology throughout
□ Grammar/spelling checked

---

Anti-Patterns

Anti-Pattern	Why Bad	Fix
Installation-first README	Buries value proposition	Lead with TL;DR
"This is a tool that..."	Passive, abstract	"Solves X by doing Y"
Screenshot-heavy	Breaks, doesn't copy-paste	ASCII + code blocks
No examples	Abstract claims don't sell	Every feature → example
Hiding limitations	Users discover painfully	Honest Limitations section
Single install method	Alienates users	curl + pkg manager + source
No troubleshooting	Support burden	Top 5 errors with fixes
Outdated badges	Looks abandoned	Remove or keep current

---

Reference Index

I need...	Read
Hero, TL;DR, Quick Example templates	CORE-TEMPLATES.md
Comparison, Installation, Commands templates	CORE-TEMPLATES.md
Architecture, Troubleshooting, Limitations, FAQ	CORE-TEMPLATES.md
Performance, Security, Data Model sections	EXTENDED-TEMPLATES.md
API Reference, Migration, Contributing sections	EXTENDED-TEMPLATES.md
Ecosystem, Env Vars, Shell Completion	EXTENDED-TEMPLATES.md
Release Notes, Acknowledgments	EXTENDED-TEMPLATES.md
Badge markdown snippets	BADGES.md
AGENTS.md blurb format	AGENTS-MD.md
Real-world README examples to study	EXAMPLES.md
Additional prompts (New README, Section-specific)	PROMPTS.md
Quick one-page cheatsheet	QUICK-REFERENCE.md