Updating README
Overview
Maintains existing README.md files with minimal, targeted updates that preserve the original style and structure.
When to Use This Skill
Use updating-readme when:
- README exists and needs a section update
- New dependency was added
- New environment variable was introduced
- Configuration options changed
- User asks "is the README up to date?" or "check the README"
- Minor corrections or additions needed
Handoff Rules
To writing-documentation skill
Escalate to writing-documentation when:
- No README.md exists (cannot update what doesn't exist)
- README needs complete rewrite (changes exceed 50% of document)
- User requests documentation beyond just README
- README lacks standard structure and needs restructuring
From writing-documentation skill
After writing-documentation creates a README:
- This skill takes over for ongoing maintenance
- Preserve the style and structure writing-documentation established
- Apply minimal, targeted updates only
Decision Matrix
| Scenario |
Use This Skill |
Use writing-documentation |
| Update existing section |
✓ |
|
| Add new dependency to README |
✓ |
|
| Add environment variable docs |
✓ |
|
| Fix outdated instructions |
✓ |
|
| Check if README current |
✓ |
|
| No README exists |
|
✓ |
| Complete README rewrite |
|
✓ |
| README + other docs needed |
|
✓ |
README Section Taxonomy
| Section |
Update Triggers |
| Title/Badges |
Version bumps, CI status changes, new integrations |
| Description |
Major feature additions, project scope changes |
| Features |
New capabilities added, features deprecated |
| Prerequisites |
Runtime version changes, new system requirements |
| Installation |
New dependencies, setup steps change |
| Configuration |
New env vars, config file changes |
| Usage |
API changes, new examples needed |
| Development |
Dev tooling changes, new scripts |
| Testing |
Test framework changes, new test commands |
| Deployment |
Infrastructure changes, new deploy steps |
| Contributing |
Process changes, new guidelines |
Change Detection
When checking if README needs updates, first read references/patterns.md for language-specific regex patterns, then use these detection rules:
Dependency Files → Installation Section
- package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile
Environment Files → Configuration Section
- .env.example changes
- New
process.env.* or os.environ[*] in code
Source Structure → Multiple Sections
- New directories in src/ → may need Architecture section
- New entry points → Usage section
- New CLI commands → Usage section
CI/CD Files → Development/Deployment
- .github/workflows/* changes
- Dockerfile, docker-compose.yml changes
Update Methodology
Step 1: Detect What Changed
Run the check script:
python .claude/skills/updating-readme/scripts/check-readme.py
Review output to identify:
- Which files changed since last README update
- Which README sections are affected
- Priority of updates needed
Step 2: Preserve Existing Style
Before making changes, note:
- Emoji usage (or lack thereof)
- Heading hierarchy and formatting
- Voice and tone
- Any custom sections
Step 3: Apply Minimal Updates
- Add new information without rewriting existing content
- Update version numbers and requirements inline
- Add new list items to existing lists
- Only restructure if absolutely necessary
Step 4: Validate
After applying updates, run verification:
Run audit:
python .claude/skills/updating-readme/scripts/check-readme.py
Verify:
- All HIGH PRIORITY issues are resolved
- No new issues introduced by your changes
- Style consistency maintained
If issues remain, fix and re-run until clean.
Templates for Missing Sections
When adding a section that doesn't exist, read references/templates.md and select the appropriate template:
- Prerequisites section
- Environment Variables section
- Testing section
- Development section
- Deployment section
- Troubleshooting section
Suggesting vs. Applying
- Small, obvious updates → Apply directly
- Structural changes → Suggest and explain before applying
- Ambiguous changes → Ask user for clarification
Examples
Example 1: New Dependency Added
User: "I just added redis to my project, update the README"
Process:
- Check package.json or requirements.txt for redis dependency
- Locate Installation and Prerequisites sections
- Add redis to prerequisites if system installation required
- Update installation instructions if setup steps needed
- Add Configuration section entry if REDIS_URL env var used
- Run check-readme.py to verify no issues remain
Example 2: New Feature Implemented
User: "Update README after adding the export feature"
Process:
- Identify what the export feature does from code
- Add entry to Features section
- Add usage example if API changed
- Update any relevant configuration docs
- Run check-readme.py to verify
Example 3: README Audit
User: "Check if my README is up to date"
Process:
- Run
python .claude/skills/updating-readme/scripts/check-readme.py
- Report findings organized by priority
- Offer to apply HIGH PRIORITY fixes
- Suggest MEDIUM PRIORITY improvements
1---2name: updating-readme3description: Updates existing README.md files after code changes. Use for requests to update, check, fix, or add to an existing README. Trigger phrases include "update readme", "check readme", "is the readme current", "add to readme", "fix readme", "readme out of date". Also use after adding dependencies, environment variables, or configuration. For creating new READMEs from scratch, use writing-documentation instead.4---5
6# Updating README
7
8## Overview
9
10Maintains existing README.md files with minimal, targeted updates that preserve the original style and structure.
11
12## When to Use This Skill
13
14Use updating-readme when:
15- README exists and needs a section update
16- New dependency was added
17- New environment variable was introduced
18- Configuration options changed
19- User asks "is the README up to date?" or "check the README"
20- Minor corrections or additions needed
21
22## Handoff Rules
23
24### To writing-documentation skill
25Escalate to writing-documentation when:
26- No README.md exists (cannot update what doesn't exist)
27- README needs complete rewrite (changes exceed 50% of document)
28- User requests documentation beyond just README
29- README lacks standard structure and needs restructuring
30
31### From writing-documentation skill
32After writing-documentation creates a README:
33- This skill takes over for ongoing maintenance
34- Preserve the style and structure writing-documentation established
35- Apply minimal, targeted updates only
36
37### Decision Matrix
38
39| Scenario | Use This Skill | Use writing-documentation |
40|----------|----------------|---------------------------|
41| Update existing section | ✓ | |
42| Add new dependency to README | ✓ | |
43| Add environment variable docs | ✓ | |
44| Fix outdated instructions | ✓ | |
45| Check if README current | ✓ | |
46| No README exists | | ✓ |
47| Complete README rewrite | | ✓ |
48| README + other docs needed | | ✓ |
49
50## README Section Taxonomy
51
52| Section | Update Triggers |
53|---------|-----------------|
54| **Title/Badges** | Version bumps, CI status changes, new integrations |
55| **Description** | Major feature additions, project scope changes |
56| **Features** | New capabilities added, features deprecated |
57| **Prerequisites** | Runtime version changes, new system requirements |
58| **Installation** | New dependencies, setup steps change |
59| **Configuration** | New env vars, config file changes |
60| **Usage** | API changes, new examples needed |
61| **Development** | Dev tooling changes, new scripts |
62| **Testing** | Test framework changes, new test commands |
63| **Deployment** | Infrastructure changes, new deploy steps |
64| **Contributing** | Process changes, new guidelines |
65
66## Change Detection
67
68When checking if README needs updates, first read `references/patterns.md` for language-specific regex patterns, then use these detection rules:
69
70### Dependency Files → Installation Section
71- package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile
72
73### Environment Files → Configuration Section
74- .env.example changes
75- New `process.env.*` or `os.environ[*]` in code
76
77### Source Structure → Multiple Sections
78- New directories in src/ → may need Architecture section
79- New entry points → Usage section
80- New CLI commands → Usage section
81
82### CI/CD Files → Development/Deployment
83- .github/workflows/* changes
84- Dockerfile, docker-compose.yml changes
85
86## Update Methodology
87
88### Step 1: Detect What Changed
89Run the check script:
90```bash
91python .claude/skills/updating-readme/scripts/check-readme.py
92```
93
94Review output to identify:
95- Which files changed since last README update
96- Which README sections are affected
97- Priority of updates needed
98
99### Step 2: Preserve Existing Style
100Before making changes, note:
101- Emoji usage (or lack thereof)
102- Heading hierarchy and formatting
103- Voice and tone
104- Any custom sections
105
106### Step 3: Apply Minimal Updates
107- Add new information without rewriting existing content
108- Update version numbers and requirements inline
109- Add new list items to existing lists
110- Only restructure if absolutely necessary
111
112### Step 4: Validate
113
114After applying updates, run verification:
115
1161. **Run audit**:
117 ```bash
118 python .claude/skills/updating-readme/scripts/check-readme.py
119 ```
120
1212. **Verify**:
122 - All HIGH PRIORITY issues are resolved
123 - No new issues introduced by your changes
124 - Style consistency maintained
125
1263. **If issues remain**, fix and re-run until clean.
127
128## Templates for Missing Sections
129
130When adding a section that doesn't exist, read `references/templates.md` and select the appropriate template:
131- Prerequisites section
132- Environment Variables section
133- Testing section
134- Development section
135- Deployment section
136- Troubleshooting section
137
138## Suggesting vs. Applying
139
140- **Small, obvious updates** → Apply directly
141- **Structural changes** → Suggest and explain before applying
142- **Ambiguous changes** → Ask user for clarification
143
144## Examples
145
146### Example 1: New Dependency Added
147
148**User:** "I just added redis to my project, update the README"
149
150**Process:**
1511. Check package.json or requirements.txt for redis dependency
1522. Locate Installation and Prerequisites sections
1533. Add redis to prerequisites if system installation required
1544. Update installation instructions if setup steps needed
1555. Add Configuration section entry if REDIS_URL env var used
1566. Run check-readme.py to verify no issues remain
157
158### Example 2: New Feature Implemented
159
160**User:** "Update README after adding the export feature"
161
162**Process:**
1631. Identify what the export feature does from code
1642. Add entry to Features section
1653. Add usage example if API changed
1664. Update any relevant configuration docs
1675. Run check-readme.py to verify
168
169### Example 3: README Audit
170
171**User:** "Check if my README is up to date"
172
173**Process:**
1741. Run `python .claude/skills/updating-readme/scripts/check-readme.py`
1752. Report findings organized by priority
1763. Offer to apply HIGH PRIORITY fixes
1774. Suggest MEDIUM PRIORITY improvements
majiayu000