| name | update-readme |
| description | This skill should be used when the user asks to "update my README", "refresh the README", "README is outdated", "sync README with the codebase", "improve my README", "keep README up to date", "fix the README", "my README is stale", "update the readme file", "README needs updating", "update readme from git history", or "readme is out of date".
|
| allowed-tools | ["Read","Glob","Grep","Write","Edit","Task","AskUserQuestion","Skill"] |
Update README
Refresh an existing README.md using current codebase state, git history, and
changelog intelligence. Always updates CHANGELOG.md first so changelog content
is available when revising README sections.
Step 1 — Check README Existence
Glob for README.md, readme.md, and Readme.md in the working directory.
If not found, or if the file has fewer than 5 lines of real content:
- Inform the user no substantial README was found
- Invoke
Skill: claude-coding:make-readme
- Stop — make-readme handles creation from scratch
If a substantial README exists: continue.
Step 2 — Update Changelog
Invoke Skill: claude-coding:make-changelog.
make-changelog detects fill mode automatically — it adds only versions missing
since the last documented entry. If the repo has no git history, make-changelog
will report an error; note it and continue without changelog context.
Step 3 — Parallel Research
Record the current README line count before edits.
Launch the three agents below in a single message (all in parallel):
Agent A — README Audit (subagent_type: Explore)
Prompt:
Read README.md. For each section (every H1/H2/H3 heading), record:
- Section name and approximate line count
- Stale content: version numbers, paths, commands, or features that look incorrect
- Placeholder text never replaced (e.g. "YOUR_USERNAME", "TODO", angle-bracket values)
- Thin sections with fewer than 3 lines of real content
Also identify which standard sections are MISSING:
installation, usage, configuration, API reference, contributing, license.
Return structured notes:
- existing_sections: list of heading names
- stale_items: list of {location, description} objects
- missing_sections: list
- thin_sections: list
Agent B — Codebase Scan (subagent_type: Explore)
Prompt:
Scan the working directory to extract:
- Project name and current version from the first found manifest:
package.json, pyproject.toml, Cargo.toml, go.mod, .claude-plugin/plugin.json
- Primary language and framework (file extensions, config files)
- Top-level directory structure, max 2 levels deep
- Key public-facing files: entry points, config templates, example files, CLI scripts
- Documentation files beyond README: CONTRIBUTING.md, docs/, ARCHITECTURE.md, etc.
Return: project_name, version, language, framework, structure_summary,
key_files (paths), extra_docs (paths).
Agent C — Git History Since Last README Touch (subagent_type: Explore)
Prompt:
Run: git log --follow -1 --format="%ai" -- README.md
This gives the date README.md was last committed.
If README.md has no git history, use the initial commit date:
git log --reverse --format="%ai" | head -1
Then run: git log --since="[date from above]" --format="%s" --no-merges
Categorize each commit subject into:
- new_features: new capabilities users can invoke
- breaking_changes: removed or incompatible changes
- deprecations: features flagged for future removal
- significant_fixes: user-visible bug fixes
- other: everything else
Skip: merge commits, CI/CD changes, formatting/whitespace, version-bump commits.
Return: readme_last_updated (ISO date), changes_since (object with 5 category lists).
Wait for all three agents to complete before Step 4.
Step 4 — Read Updated Changelog
Read CHANGELOG.md and extract the most recent version section (the first ## [x.y.z]
block). This provides structured change context for README sections like Features.
Step 5 — Synthesize and Update
Apply targeted updates to README.md. Preserve existing style, header format,
badge patterns, and overall structure — do not restructure unless clearly broken.
Apply in this priority order — highest-confidence fixes first, judgment-heavy
additions last, because objective errors (wrong version, broken path) have
deterministic answers while structural additions require codebase context to get right:
- Version/badge updates — update all version numbers and shields.io badge
URLs to the version from Agent B
- Stale content — correct outdated paths, commands, flags, or removed features
flagged by Agent A
- Placeholder cleanup — replace any unfilled placeholders with real values
from Agent B
- New features — add or expand the Features section using Agent C's
new_features list and the latest CHANGELOG section
- Missing sections — add any standard sections identified by Agent A as
absent, with minimal viable content drawn from Agent B's codebase scan
- Thin sections — expand underdeveloped sections using Agent B context
If no updates are needed after applying all criteria, skip edits and proceed to Step 6.
For each change, make the smallest edit that achieves accuracy. Use Edit for
targeted section updates — it preserves git blame and is safer for incremental
changes. Use Write only if more than 60% of the file changes, because at that
point the document is being regenerated, not updated.
Step 6 — Report
Output a diff summary after writing:
- Line count: N → M lines
- Sections updated: list with one-line description of each change
- Sections added: list
- Sections removed: list with reason (if any)
- Version bumped: old → new (if applicable)
- Changelog: versions added by make-changelog
