Update Readme
Refresh a stale README from the real repo—changelog, git history, and parallel codebase research—without rewriting from scratch.
Overview
update-readme is an agent skill most often used in Build (also Launch distribution, Validate landing) that refreshes README.md from changelog, git history, and parallel codebase research.
Install
npx skills add https://github.com/gupsammy/claudest --skill update-readmeWhat is this skill?
- Runs make-changelog first so README sections can cite up-to-date release notes
- Falls back to make-readme when no substantial README exists (under 5 lines)
- Parallel research agents scan codebase, git history, and project metadata before edits
- Tracks pre-edit line count to avoid uncontrolled README bloat
Adoption & trust: 1 installs on skills.sh; 253 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your README still describes last quarter’s architecture while CHANGELOG and git tell a different story.
Who is it for?
Maintainers of active repos who want README and changelog kept in sync without manual archaeology every release.
Skip if: Empty repos with no git history (changelog step may fail) or teams that want a brand-new README from zero without an update pass.
When should I use this skill?
User asks to update, refresh, sync, fix, or keep README up to date; README is stale or outdated.
What do I get? / Deliverables
CHANGELOG is updated first, then README sections are revised from fresh repo research—or make-readme is invoked if no real README exists.
- Updated README.md
- Updated CHANGELOG.md via chained make-changelog
- Handoff to make-readme when no README exists
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
README maintenance is canonical Build/docs work because it syncs the repo’s public face with implementation reality. The workflow edits README.md using changelog and code intelligence—documentation artifacts, not feature code.
Where it fits
After merging a feature branch, regenerate README install and config sections from the current tree.
Before tagging a release, align README badges and quickstart with what npm or PyPI will show.
Polish the github.com landing copy so early testers see accurate setup steps.
Refresh contributor and roadmap sections so community PRs reference the right commands.
How it compares
Structured README refresh tied to changelog—instead of one-shot chat paraphrasing of old markdown.
Common Questions / FAQ
Who is update-readme for?
Solo and indie builders shipping open source or product repos who already have a README but need it aligned with current code and releases.
When should I use update-readme?
In Build when docs are stale; before Launch when repo README is your distribution landing; after aValidate prototype when you want the public readme to match scope.
Is update-readme safe to install?
It writes README and changelog files—review diffs before merge and check the Security Audits panel on this Prism page for the skill package.
Workflow Chain
Requires first: make changelog
SKILL.md
READMESKILL.md - Update Readme
# 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 a