Readme Writing

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

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

Reference Index