用途：让文档与本次代码或 skill 变更保持一致，包括写入 CHANGELOG、同步使用说明、保持各处版本号一致。
仓库路由：先确认变更属于哪个仓库。ValorVie/custom-skills 涵盖 ai-dev CLI、commands、agents、plugins、project-template、OpenSpec 与框架文档；ValorVie/ai-dev-skills 涵盖第一方 skill 内容、skill 测试、集合 README 与 CHANGELOG。跨仓库变更需分开检查、分开提交；不得把 skill 内容复制回框架仓库，也不得把 ai-dev 运行时文档放进 skill 目录冒充自包含内容。
范围与参数：未指定范围时分析最近 1 个 commit，并在结果开头写明采用范围，用 git log、git diff --stat、git diff 读取变更。支持无参数（最近 1 个 commit）、N（最近 N 个 commits）、--since <ref>（从指定 ref 开始）、--check（只回报需更新的文档，不修改）。
变更类型与文档：按路径判断类型，如 skills//*.md 为 Skill 变更、agents//.md 为 Agent 变更、commands/**/.md 为 Command 变更、plugins//* 为 Plugin 变更、script//.py 为 CLI 功能变更、pyproject.toml 为版本发布、openspec/specs/**/ 为 Spec 变更、upstream//* 为上游整合、docs//* 为文档变更。再按类型确定“一定要更新”与“视情况更新”的文档；表中未列的文档用变更中的文件名、功能名或指令名搜索 *.md 找出。Plugin 改版本时，plugins/<name>/.claude-plugin/plugin.json 与 package.json（若有）的 version 需与 CHANGELOG 一致。
更新方式：改任何文档前先读它，沿用现有格式与段落结构。CHANGELOG 依 Keep a Changelog 格式，各类文件格式见 references/doc-formats.md。文档用繁体中文，Skill、Command、Agent、Hook、Plugin、CLI、TUI、MCP、API、Git、GitHub、upstream 等技术词保留英文。--check 时只回报，不修改任何文件。
完成检查：确认“一定要更新”的文档已更新或已写出不更新原因；pyproject.toml、plugin.json、package.json 与 CHANGELOG 版本号一致；同一功能在各文档说法一致、链接有效。最后回报分析范围、已更新文档与内容、判断不需更新的文档及原因、版本一致性结果。具体安装命令与更多细节暂未提供。