update-readme

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update README

更新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.

利用当前代码库状态、Git历史和变更日志智能刷新现有的

README.md

。始终先更新

CHANGELOG.md

，以便在修订README章节时可以使用变更日志内容。

Step 1 — Check README Existence

步骤1 — 检查README是否存在

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.

在工作目录中查找

README.md

、

readme.md

和

Readme.md

。

如果未找到，或者文件的有效内容不足5行：

告知用户未找到实质性的README
调用
```
Skill: claude-coding:make-readme
```
停止操作——make-readme负责从头创建README

如果存在实质性的README：继续下一步。

Step 2 — Update Changelog

步骤2 — 更新变更日志

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.

调用

Skill: claude-coding:make-changelog

。

make-changelog会自动检测填充模式——它仅添加自上次记录条目以来缺失的版本。如果仓库没有Git历史，make-changelog会报告错误；记录该错误并在没有变更日志上下文的情况下继续操作。

Step 3 — Parallel Research

步骤3 — 并行调研

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.

在编辑前记录当前README的行数。

在一条消息中启动以下三个Agent（全部并行执行）：

Agent A — README审核 (

subagent_type: Explore

)

提示词：

阅读README.md。针对每个章节（每个H1/H2/H3标题），记录：
- 章节名称和大致行数
- 过时内容：版本号、路径、命令或看起来不正确的功能
- 从未替换的占位符文本（例如"YOUR_USERNAME"、"TODO"、尖括号包裹的值）
- 有效内容不足3行的单薄章节

同时识别缺失的标准章节：
installation（安装）、usage（使用）、configuration（配置）、API reference（API参考）、contributing（贡献）、license（许可证）。

返回结构化笔记：
- existing_sections: 标题名称列表
- stale_items: {location, description}对象列表
- missing_sections: 列表
- thin_sections: 列表

Agent B — 代码库扫描 (

subagent_type: Explore

)

提示词：

扫描工作目录以提取：
- 从第一个找到的清单文件中获取项目名称和当前版本：
  package.json、pyproject.toml、Cargo.toml、go.mod、.claude-plugin/plugin.json
- 主要语言和框架（文件扩展名、配置文件）
- 顶级目录结构，最多2层深度
- 关键面向公众的文件：入口点、配置模板、示例文件、CLI脚本
- README之外的文档文件：CONTRIBUTING.md、docs/、ARCHITECTURE.md等

返回：project_name、version、language、framework、structure_summary、
key_files（路径）、extra_docs（路径）。

Agent C — 上次修改README后的Git历史 (

subagent_type: Explore

)

提示词：

运行：git log --follow -1 --format="%ai" -- README.md
这会给出README.md上次提交的日期。
如果README.md没有Git历史，则使用初始提交日期：
  git log --reverse --format="%ai" | head -1

然后运行：git log --since="[上述日期]" --format="%s" --no-merges

将每个提交主题分类为：
- new_features: 用户可以调用的新功能
- breaking_changes: 已移除或不兼容的变更
- deprecations: 标记为未来移除的功能
- significant_fixes: 用户可见的错误修复
- other: 其他所有内容

跳过：合并提交、CI/CD变更、格式/空白字符变更、版本号更新提交。

返回：readme_last_updated（ISO日期）、changes_since（包含5个分类列表的对象）。

等待所有三个Agent完成后再进入步骤4。

Step 4 — Read Updated Changelog

步骤4 — 读取更新后的变更日志

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.

读取

CHANGELOG.md

并提取最新版本章节（第一个

## [x.y.z]

块）。这为Features（功能）等README章节提供结构化的变更上下文。

Step 5 — Synthesize and Update

步骤5 — 合成与更新

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.

对

README.md

进行针对性更新。保留现有样式、标题格式、徽章模式和整体结构——除非明显损坏，否则不要重构。

按以下优先级顺序应用更新——先进行可信度最高的修复，最后进行需要判断的添加，因为客观错误（错误的版本、无效路径）有确定的答案，而结构添加需要代码库上下文才能正确实现：

版本/徽章更新——将所有版本号和shields.io徽章URL更新为Agent B获取的版本
过时内容修正——更正Agent A标记的过时路径、命令、标志或已移除功能
占位符清理——用Agent B获取的真实值替换所有未填充的占位符
新功能添加——使用Agent C的
```
new_features
```
列表和最新变更日志章节添加或扩展Features章节
缺失章节补充——添加Agent A识别出的所有缺失标准章节，使用Agent B的代码库扫描结果生成最小可行内容
单薄章节扩展——利用Agent B的上下文扩展内容不足的章节

如果应用所有标准后无需更新，则跳过编辑并进入步骤6。

对于每项变更，做出能实现准确性的最小修改。使用

Edit

进行针对性章节更新——它保留git blame，更适合增量变更。仅当超过60%的文件内容需要变更时才使用

Write

，因为此时文档是被重新生成，而非更新。

Step 6 — Report

步骤6 — 报告

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

编写完成后输出差异摘要：

行数：N → M行
更新的章节：包含每项变更单行描述的列表
添加的章节：列表
移除的章节：包含原因（如有）的列表
版本更新：旧版本 → 新版本（如适用）
变更日志：make-changelog添加的版本