docs-updater

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Universal Documentation Auto-Updater

通用文档自动更新工具

Automates the process of keeping project documentation synchronized with codebase changes. This skill analyzes git differences between the current working branch and the last released version, then intelligently updates relevant documentation files.

可自动完成项目文档与代码库变更的同步流程。该skill会分析当前工作分支与最新发布版本之间的git差异，然后智能更新相关文档文件。

Overview

概述

The Universal Documentation Auto-Updater provides a language-agnostic approach to documentation maintenance. By leveraging git operations to identify what has changed since the last release, it generates targeted updates for README.md, CHANGELOG.md, and project documentation folders.

Key Features:

Universal Compatibility: Works with any git repository regardless of programming language
Dynamic Version Detection: Automatically finds the latest release tag
Comprehensive Diff Analysis: Analyzes additions, modifications, and deletions
Smart Categorization: Groups changes by type (feature, fix, refactor, docs, etc.)
Documentation Discovery: Automatically finds and updates relevant docs folders

通用文档自动更新工具提供了跨语言的文档维护方案。通过git操作识别自上一个版本发布以来的所有变更，它会为README.md、CHANGELOG.md以及项目文档文件夹生成针对性的更新内容。

核心功能：

通用兼容性：适用于任何git仓库，不受编程语言限制
动态版本检测：自动查找最新的发布tag
全面差异分析：分析新增、修改、删除的所有内容
智能分类：按类型对变更分组（功能、修复、重构、文档等）
文档自动发现：自动查找并更新相关的文档文件夹

When to Use

适用场景

Use this skill when:

Preparing documentation for a new release
The documentation has fallen behind the codebase
Creating a pull request and need to update docs
Asked to "update changelog", "update docs", "sync documentation"
Want to see what changed since the last release
Need to generate release notes

Trigger phrases: "update docs", "update changelog", "sync documentation", "update readme", "prepare release documentation", "what changed since last release", "generate release notes"

在以下情况使用该skill：

为新版本发布准备文档
文档落后于代码库迭代进度
创建pull request时需要更新文档
收到"update changelog"、"update docs"、"sync documentation"这类需求
需要查看自上一次发布以来的变更内容
需要生成发布说明

触发短语： "update docs"、"update changelog"、"sync documentation"、"update readme"、"prepare release documentation"、"what changed since last release"、"generate release notes"

Prerequisites

前置条件

Before starting, verify that the following conditions are met:

bash

undefined

开始使用前，请确认满足以下条件：

bash

undefined

Verify we're in a git repository

验证当前处于git仓库中

git rev-parse --git-dir

Check that git tags exist

检查是否存在git标签

git tag --list | head -5

Verify documentation files exist

验证文档文件存在

test -f README.md || echo "README.md not found" test -f CHANGELOG.md || echo "CHANGELOG.md not found"


If no tags exist, inform the user that this skill requires at least one release tag to compare against.

test -f README.md || echo "README.md not found" test -f CHANGELOG.md || echo "CHANGELOG.md not found"


如果不存在任何标签，请告知用户该skill需要至少一个发布tag作为对比基准。

Instructions

使用说明

Phase 1: Detect Last Release Version

阶段1：检测上一个发布版本

Goal: Identify the latest released version to compare against.

Actions:

Get the latest tag from the repository:

bash

undefined

目标：识别用于对比的最新发布版本。

操作步骤：

从仓库中获取最新标签：

bash

undefined

Get the most recent tag

获取最近的tag

LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

If no tags found, inform the user

未找到标签时告知用户

if [ -z "$LATEST_TAG" ]; then echo "No git tags found. This skill requires at least one release tag." echo "Please create a release tag first (e.g., git tag -a v1.0.0 -m 'Initial release')" exit 1 fi

echo "Latest release tag: $LATEST_TAG" echo "Current branch: $(git branch --show-current)"


2. Extract version information for display:

```bash

if [ -z "$LATEST_TAG" ]; then echo "No git tags found. This skill requires at least one release tag." echo "Please create a release tag first (e.g., git tag -a v1.0.0 -m 'Initial release')" exit 1 fi

echo "Latest release tag: $LATEST_TAG" echo "Current branch: $(git branch --show-current)"


2. 提取版本信息用于展示：

```bash

Parse version from tag (handles v1.2.3, 1.2.3, release-1.2.3 formats)

从标签中解析版本（支持v1.2.3、1.2.3、release-1.2.3等格式）

VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]([0-9]+.[0-9]+.[0-9]+)./\1/') echo "Version detected: $VERSION"


3. Get the current branch name:

```bash
CURRENT_BRANCH=$(git branch --show-current)
echo "Comparing: $LATEST_TAG -> $CURRENT_BRANCH"

VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]([0-9]+.[0-9]+.[0-9]+)./\1/') echo "Version detected: $VERSION"


3. 获取当前分支名称：

```bash
CURRENT_BRANCH=$(git branch --show-current)
echo "Comparing: $LATEST_TAG -> $CURRENT_BRANCH"

Phase 2: Perform Git Diff Analysis

阶段2：执行Git Diff分析

Goal: Analyze all changes between the last release and current branch.

Actions:

Get the commit range and statistics:

bash

undefined

目标：分析上一个发布版本与当前分支之间的所有变更。

操作步骤：

获取提交范围和统计信息：

bash

undefined

Get commit count between tag and HEAD

获取tag到HEAD之间的提交数量

COMMIT_COUNT=$(git rev-list --count ${LATEST_TAG}..HEAD 2>/dev/null || echo "0") echo "Commits since $LATEST_TAG: $COMMIT_COUNT"

Get file change statistics

获取文件变更统计

git diff --stat ${LATEST_TAG}..HEAD


2. Extract commit messages for analysis:

```bash

git diff --stat ${LATEST_TAG}..HEAD


2. 提取提交信息用于分析：

```bash

Get all commit messages in the range

获取范围内的所有提交信息

COMMITS=$(git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%b" --reverse)

Display commits for review

展示提交以供审核

echo "$COMMITS"


3. Get detailed file changes:

```bash

echo "$COMMITS"


3. 获取详细的文件变更：

```bash

Get list of changed files

获取变更文件列表

CHANGED_FILES=$(git diff --name-only ${LATEST_TAG}..HEAD)

Categorize changes by type

按类型对变更分类

ADDED_FILES=$(git diff --name-only --diff-filter=A ${LATEST_TAG}..HEAD) DELETED_FILES=$(git diff --name-only --diff-filter=D ${LATEST_TAG}..HEAD) MODIFIED_FILES=$(git diff --name-only --diff-filter=M ${LATEST_TAG}..HEAD)


4. Identify component areas based on file paths:

```bash


4. 根据文件路径识别变更的组件领域：

```bash

Detect which components/areas changed

检测哪些组件/领域发生了变更

echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u

undefined

echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u

undefined

Phase 3: Discover Documentation Structure

阶段3：发现文档结构

Goal: Identify all relevant documentation locations in the project.

Actions:

Find standard documentation folders:

bash

undefined

目标：识别项目中所有相关的文档位置。

操作步骤：

查找标准文档文件夹：

bash

undefined

Check for common documentation locations

检查常见的文档存储位置

DOC_FOLDERS=()

[ -d "docs" ] && DOC_FOLDERS+=("docs/") [ -d "documentation" ] && DOC_FOLDERS+=("documentation/") [ -d "doc" ] && DOC_FOLDERS+=("doc/")

DOC_FOLDERS=()

[ -d "docs" ] && DOC_FOLDERS+=("docs/") [ -d "documentation" ] && DOC_FOLDERS+=("documentation/") [ -d "doc" ] && DOC_FOLDERS+=("doc/")

Find plugin-specific docs

查找插件专属文档

for plugin_dir in plugins/*/; do if [ -d "${plugin_dir}docs" ]; then DOC_FOLDERS+=("${plugin_dir}docs/") fi done

echo "Documentation folders found:" printf ' - %s\n' "${DOC_FOLDERS[@]}"


2. Identify existing documentation files:

```bash

for plugin_dir in plugins/*/; do if [ -d "${plugin_dir}docs" ]; then DOC_FOLDERS+=("${plugin_dir}docs/") fi done

echo "Documentation folders found:" printf ' - %s\n' "${DOC_FOLDERS[@]}"


2. 识别已有的文档文件：

```bash

Check for standard doc files

检查标准文档文件

DOC_FILES=()

[ -f "README.md" ] && DOC_FILES+=("README.md") [ -f "CHANGELOG.md" ] && DOC_FILES+=("CHANGELOG.md") [ -f "CONTRIBUTING.md" ] && DOC_FILES+=("CONTRIBUTING.md") [ -f "docs/GUIDE.md" ] && DOC_FILES+=("docs/GUIDE.md")

echo "Documentation files found:" printf ' - %s\n' "${DOC_FILES[@]}"

undefined

DOC_FILES=()

echo "Documentation files found:" printf ' - %s\n' "${DOC_FILES[@]}"

undefined

Phase 4: Generate CHANGELOG Updates

阶段4：生成CHANGELOG更新内容

Goal: Create categorized changelog entries following Keep a Changelog standard.

Actions:

Parse commits by conventional commit types and categorize:

Added: New features (feat, feature commits)
Changed: Changes to existing functionality
Fixed: Bug fixes (fix, bug commits)
Deprecated: Soon-to-be removed features
Removed: Features removed in this release
Security: Security vulnerability fixes

Read the existing CHANGELOG.md to understand structure, then generate new entries following Keep a Changelog format.

See

references/examples.md

for detailed bash commands and changelog templates.

目标：遵循Keep a Changelog标准创建分类的更新日志条目。

操作步骤：

按约定式提交类型解析提交并分类：

新增（Added）：新功能（feat、feature类提交）
变更（Changed）：对现有功能的修改
修复（Fixed）：漏洞修复（fix、bug类提交）
弃用（Deprecated）：即将移除的功能
移除（Removed）：本次发布中移除的功能
安全（Security）：安全漏洞修复

读取现有CHANGELOG.md了解结构，然后按照Keep a Changelog格式生成新条目。

查看

references/examples.md

获取详细的bash命令和更新日志模板。

Phase 5: Update README.md

阶段5：更新README.md

Goal: Update the main README with relevant high-level changes.

Actions:

Read the current README.md to understand its structure
Identify sections needing updates (features list, skills/agents, setup instructions, version references)
Apply updates using Edit tool: preserve structure, maintain tone, update version numbers

目标：使用相关的高层变更内容更新主README文件。

操作步骤：

读取当前README.md了解其结构
识别需要更新的部分（功能列表、skill/agent、配置说明、版本引用）
使用编辑工具应用更新：保留结构、保持文风、更新版本号

Phase 6: Update Documentation Folders

阶段6：更新文档文件夹

Goal: Propagate changes to relevant documentation in docs/ folders.

Actions:

For each documentation folder found, check for files referencing changed code
Map changed files to their documentation
Generate updates: add new feature docs, update API references, fix outdated examples

See

references/examples.md

for detailed discovery patterns and update strategies.

目标：将变更同步到docs/文件夹下的相关文档中。

操作步骤：

对每个发现的文档文件夹，检查引用了变更代码的文件
将变更文件映射到对应的文档
生成更新内容：新增功能文档、更新API引用、修复过时示例

查看

references/examples.md

获取详细的发现规则和更新策略。

Phase 7: Present Changes for Review

阶段7：展示变更以供审核

Goal: Show the user what will be updated before applying changes.

Actions:

Present a summary of proposed changes:

markdown

undefined

目标：在应用变更前向用户展示即将更新的内容。

操作步骤：

展示拟议变更的摘要：

markdown

undefined

Proposed Documentation Updates

拟议的文档更新

Version Information

版本信息

Previous release: $LATEST_TAG
Current branch: $CURRENT_BRANCH
Commits analyzed: $COMMIT_COUNT

上一个发布版本: $LATEST_TAG
当前分支: $CURRENT_BRANCH
分析的提交数: $COMMIT_COUNT

Files to Update

待更新文件

CHANGELOG.md - Add new version section with categorized changes
README.md - Update [specific sections]
docs/[specific files] - Update documentation

CHANGELOG.md - 新增带分类变更的新版本章节
README.md - 更新[特定章节]
docs/[特定文件] - 更新文档

Summary of Changes

变更摘要

Added: N new features Changed: N modifications Fixed: N bug fixes Breaking: N breaking changes


2. Ask the user for confirmation via **AskUserQuestion**:

- Confirm which files to update
- Ask if any changes should be modified
- Get approval to proceed

新增: N项新功能变更: N项修改修复: N个漏洞修复 破坏性变更: N项破坏性变更


2. 通过**AskUserQuestion**向用户请求确认：

- 确认需要更新哪些文件
- 询问是否需要修改任何变更内容
- 获取执行更新的许可

Phase 8: Apply Documentation Updates

阶段8：应用文档更新

Goal: Write the updates to the documentation files.

Actions:

Update CHANGELOG.md:

bash

undefined

目标：将更新内容写入文档文件。

操作步骤：

更新CHANGELOG.md：

bash

undefined

Read current changelog

读取当前更新日志

CURRENT_CHANGELOG=$(cat CHANGELOG.md)

Prepend new section

插入新章节

cat > CHANGELOG.md << 'EOF'

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[New content goes here]

[Rest of existing changelog] EOF


2. Update README.md using Edit tool:

- Make targeted edits to specific sections
- Preserve overall structure
- Update version numbers if applicable

3. Update documentation files:

```bash

[New content goes here]

[Rest of existing changelog] EOF


2. 使用编辑工具更新README.md：

- 对特定章节进行针对性编辑
- 保留整体结构
- 如有需要更新版本号

3. 更新文档文件：

```bash

For each documentation file that needs updates

对每个需要更新的文档文件

Use Edit tool to make precise changes

使用编辑工具进行精准修改


4. Show git diff of changes:

```bash


4. 展示变更的git diff：

```bash

Show what will change

展示即将发生的变更

git diff CHANGELOG.md git diff README.md git diff docs/

undefined

git diff CHANGELOG.md git diff README.md git diff docs/

undefined

Examples

示例

Example 1: Update After Feature Development

示例1：功能开发完成后的更新

User request: "Update docs for the new features I just added"

Output:

Latest tag: v2.4.1 → Current branch: develop
5 commits analyzed
CHANGELOG entry generated for new Spring Boot Actuator skill
README.md skills list updated

用户请求： "Update docs for the new features I just added"

输出：

最新tag: v2.4.1 → 当前分支: develop
分析了5条提交
为新的Spring Boot Actuator skill生成了CHANGELOG条目
更新了README.md的skill列表

Example 2: Prepare Release Documentation

示例2：版本发布文档准备

User request: "Prepare documentation for v2.5.0 release"

Output:

47 commits analyzed since v2.4.1
15 features, 8 fixes, 3 breaking changes detected
Complete CHANGELOG.md [2.5.0] section generated
README.md and plugin docs updated

用户请求： "Prepare documentation for v2.5.0 release"

输出：

分析了自v2.4.1以来的47条提交
检测到15项功能、8项修复、3项破坏性变更
生成了完整的CHANGELOG.md [2.5.0]章节
更新了README.md和插件文档

Example 3: Incremental Sync

示例3：增量同步

User request: "Sync docs, I've made some changes"

Output:

2 commits analyzed
Focused CHANGELOG update for github-issue-workflow skill changes
No README or plugin doc updates needed

See

references/examples.md

for detailed session transcripts and troubleshooting.

用户请求： "Sync docs, I've made some changes"

输出：

分析了2条提交
针对github-issue-workflow skill的变更完成了针对性的CHANGELOG更新
不需要更新README或插件文档

查看

references/examples.md

获取完整的会话记录和故障排查指南。

Best Practices

最佳实践

Always verify before writing: Show the user what will change before applying updates
Follow Keep a Changelog: Maintain consistent changelog formatting
Categorize properly: Use correct categories (Added, Changed, Fixed, etc.)
Be specific: Include plugin/component names in changelog entries
Preserve structure: Maintain existing documentation structure and style
Reference commits: Include commit hashes for traceability when helpful
Handle breaking changes: Clearly highlight breaking changes with migration notes
Update version refs: Keep version numbers consistent across documentation

写入前始终校验：应用更新前向用户展示即将变更的内容
遵循Keep a Changelog规范：保持一致的更新日志格式
正确分类：使用准确的分类（新增、变更、修复等）
内容具体：在更新日志条目中包含插件/组件名称
保留结构：维持现有文档的结构和风格
引用提交：如有帮助可包含提交哈希便于溯源
处理破坏性变更：通过迁移说明明确标注破坏性变更
更新版本引用：保持整个文档中版本号的一致性

Constraints and Warnings

约束和警告

Requires git tags: This skill only works if the repository has at least one release tag
Read-only analysis: The skill analyzes changes but asks before writing
Manual review required: Generated changelog entries should be reviewed for accuracy
Conventional commits: Works best with projects using conventional commit format
Does not create tags: This skill updates docs but does not create release tags
No auto-commit: Documentation changes are prepared but not committed automatically
Project-specific patterns: Some projects may have custom changelog formats to respect
File paths: All file paths use forward slashes (Unix style) for cross-platform compatibility

需要git标签：该skill仅适用于至少存在一个发布tag的仓库
只读分析：skill仅分析变更，写入前会征求用户同意
需要人工审核：生成的更新日志条目需要审核确认准确性
约定式提交适配：在使用约定式提交格式的项目中效果最佳
不创建标签：该skill仅更新文档，不会创建发布标签
无自动提交：文档变更仅完成准备，不会自动提交
适配项目自定义规则：部分项目可能有自定义的更新日志格式需要遵守
文件路径：所有文件路径使用正斜杠（Unix风格）以保证跨平台兼容性