update-readme

Original：🇺🇸 English

Translated

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".

5installs

Sourcegupsammy/claudest

Added on2026-05-25

NPX Install

npx skill4agent add gupsammy/claudest update-readme

SKILL.md Content

View Translation Comparison →

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

update-readme

NPX Install

Tags

SKILL.md Content

Update README

Step 1 — Check README Existence

Step 2 — Update Changelog

Step 3 — Parallel Research

Step 4 — Read Updated Changelog

Step 5 — Synthesize and Update

Step 6 — Report