Crafting Effective READMEs
v2.88 Key Changes (MODEL-AGNOSTIC)
- Model-agnostic: Uses model configured in
~/.claude/settings.json or CLI/env vars
- No flags required: Works with the configured default model
- Flexible: Works with GLM-5, Claude, Minimax, or any configured model
- Settings-driven: Model selection via
ANTHROPIC_DEFAULT_*_MODEL env vars
Overview
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
Always ask: Who will read this, and what do they need to know?
Process
Step 1: Identify the Task
Ask: "What README task are you working on?"
| Task |
When |
| Creating |
New project, no README yet |
| Adding |
Need to document something new |
| Updating |
Capabilities changed, content is stale |
| Reviewing |
Checking if README is still accurate |
Step 2: Task-Specific Questions
Creating initial README:
- What type of project? (see Project Types below)
- What problem does this solve in one sentence?
- What's the quickest path to "it works"?
- Anything notable to highlight?
Adding a section:
- What needs documenting?
- Where should it go in the existing structure?
- Who needs this info most?
Updating existing content:
- What changed?
- Read current README, identify stale sections
- Propose specific edits
Reviewing/refreshing:
- Read current README
- Check against actual project state (package.json, main files, etc.)
- Flag outdated sections
- Update "Last reviewed" date if present
Step 3: Always Ask
After drafting, ask: "Anything else to highlight or include that I might have missed?"
Project Types
| Type |
Audience |
Key Sections |
Template |
| Open Source |
Contributors, users worldwide |
Install, Usage, Contributing, License |
templates/oss.md |
| Personal |
Future you, portfolio viewers |
What it does, Tech stack, Learnings |
templates/personal.md |
| Internal |
Teammates, new hires |
Setup, Architecture, Runbooks |
templates/internal.md |
| Config |
Future you (confused) |
What's here, Why, How to extend, Gotchas |
templates/xdg-config.md |
Ask the user if unclear. Don't assume OSS defaults for everything.
Essential Sections (All Types)
Every README needs at minimum:
- Name - Self-explanatory title
- Description - What + why in 1-2 sentences
- Usage - How to use it (examples help)
References
section-checklist.md - Which sections to include by project typestyle-guide.md - Common README mistakes and prose guidanceusing-references.md - Guide to deeper reference materials
1---2name: crafting-effective-readmes3description: Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.4---5
6# Crafting Effective READMEs
7
8## v2.88 Key Changes (MODEL-AGNOSTIC)
9
10- **Model-agnostic**: Uses model configured in `~/.claude/settings.json` or CLI/env vars
11- **No flags required**: Works with the configured default model
12- **Flexible**: Works with GLM-5, Claude, Minimax, or any configured model
13- **Settings-driven**: Model selection via `ANTHROPIC_DEFAULT_*_MODEL` env vars
14
15## Overview
16
17READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
18
19**Always ask:** Who will read this, and what do they need to know?
20
21## Process
22
23### Step 1: Identify the Task
24
25**Ask:** "What README task are you working on?"
26
27| Task | When |
28|------|------|
29| **Creating** | New project, no README yet |
30| **Adding** | Need to document something new |
31| **Updating** | Capabilities changed, content is stale |
32| **Reviewing** | Checking if README is still accurate |
33
34### Step 2: Task-Specific Questions
35
36**Creating initial README:**
371. What type of project? (see Project Types below)
382. What problem does this solve in one sentence?
393. What's the quickest path to "it works"?
404. Anything notable to highlight?
41
42**Adding a section:**
431. What needs documenting?
442. Where should it go in the existing structure?
453. Who needs this info most?
46
47**Updating existing content:**
481. What changed?
492. Read current README, identify stale sections
503. Propose specific edits
51
52**Reviewing/refreshing:**
531. Read current README
542. Check against actual project state (package.json, main files, etc.)
553. Flag outdated sections
564. Update "Last reviewed" date if present
57
58### Step 3: Always Ask
59
60After drafting, ask: **"Anything else to highlight or include that I might have missed?"**
61
62## Project Types
63
64| Type | Audience | Key Sections | Template |
65|------|----------|--------------|----------|
66| **Open Source** | Contributors, users worldwide | Install, Usage, Contributing, License | `templates/oss.md` |
67| **Personal** | Future you, portfolio viewers | What it does, Tech stack, Learnings | `templates/personal.md` |
68| **Internal** | Teammates, new hires | Setup, Architecture, Runbooks | `templates/internal.md` |
69| **Config** | Future you (confused) | What's here, Why, How to extend, Gotchas | `templates/xdg-config.md` |
70
71**Ask the user** if unclear. Don't assume OSS defaults for everything.
72
73## Essential Sections (All Types)
74
75Every README needs at minimum:
76
771. **Name** - Self-explanatory title
782. **Description** - What + why in 1-2 sentences
793. **Usage** - How to use it (examples help)
80
81## References
82
83- `section-checklist.md` - Which sections to include by project type
84- `style-guide.md` - Common README mistakes and prose guidance
85- `using-references.md` - Guide to deeper reference materials
majiayu000