custom-skills-doc-updater

Documentation Updater

Keep documents consistent with this program or skill change: record what should go into the CHANGELOG, update the documents that explain usage accordingly, and keep version numbers consistent everywhere.

Repository routing

First confirm which repository the change belongs to:

• ValorVie/custom-skills: ai-dev CLI, commands, agents, plugins, project-template, OpenSpec, and framework documentation.
• ValorVie/ai-dev-skills: first-party skill content, skill tests, collection README, and CHANGELOG.

Cross-repository changes must be checked separately and committed separately. Do not copy skill content back into the framework repository, and do not put ai-dev runtime documentation into the skill directory to pass it off as self-contained content.

Scope

When the user does not specify a scope, analyze the most recent 1 commit, and state the adopted scope at the beginning of the result. Use git log、git diff --stat and git diff to read the changes within the scope.

Parameter	Description	Example
No parameter	Analyze the most recent 1 commit	/doc-updater
N	Analyze the most recent N commits	/doc-updater 5
--since <ref>	Start analysis from the specified ref	/doc-updater --since v1.0.0
--check	Only report documents that need updating, without modifying them	/doc-updater --check

Change types and documents to review

First determine the type based on the path of the changed file:

File path pattern	Change type
skills/**/*.md	ai-dev-skills Skill changes in the repository
agents/**/*.md	Agent changes
commands/**/*.md	Command changes
plugins/**/*	Plugin changes
script/**/*.py	CLI feature changes
pyproject.toml (version)	Version release
openspec/specs/**/*	Spec changes
upstream/**/*	Upstream integration
docs/**/*	Documentation changes (may require cross-updates)

Then find the documents to review based on the type. If a document in "must update" is judged not to need changes, write out the reason.

Change type	Must update	Update as appropriate
Plugin	CHANGELOG.md、plugins/<name>/README.md	README.md(when usage changes),docs/AI開發環境設定指南.md(when the installation process changes)
Skill	ai-dev-skills/CHANGELOG.md	ai-dev-skills/README.md(when the skill list, installation method, or boundary changes),custom-skills/upstream/npx-skills.yaml(only when the baseline adoption list changes)
Agent	CHANGELOG.md、docs/Skill-Command-Agent差異說明.md"Appendix: Built-in Agents List"	—
Command	CHANGELOG.md	List the guide for that command
CLI feature	CHANGELOG.md、README.md(command description, parameter table)	—
Version release	pyproject.toml version,CHANGELOG.md date and version number	README.md
Upstream integration	CHANGELOG.md、upstream/README.md"Integration Decision Record"	—

All types should also review README.md; when project context is involved, also review openspec/config.yaml(the old version is openspec/project.md). For documents not listed in the table, use the filenames, feature names, or command names in the changes to search *.md to find them.

When a Plugin version changes,plugins/<name>/.claude-plugin/plugin.json and package.json(if any) version must be consistent with the CHANGELOG.

Update method

• Before changing any document, read it first, and follow the existing format and section structure.
• The CHANGELOG follows the Keep a Changelog format; for the formats of various documents, see references/doc-formats.md。
• Documents use Traditional Chinese; technical terms such as Skill, Command, Agent, Hook, Plugin, CLI, TUI, MCP, API, Git, GitHub, and upstream remain in English.
• --check only report, without modifying any files.

Complete check

• All files that "must be updated" have been updated, or a reason for not updating has been written
• pyproject.toml、plugin.json、package.json Consistent with the CHANGELOG version number
• The description of the same feature is consistent across documents, and links are valid

Final report: scope of analysis, documents and content updated, documents judged not to need updating and the reasons, version consistency results.