custom-skills-doc-updater

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Updater

智能化文件更新工作流程，確保程式碼變更與文件同步。

Intelligent documentation update workflow to ensure synchronization between code changes and documentation.

Repository routing

Repository Routing

先確認變更屬於哪個 repository：

```
ValorVie/custom-skills
```
：ai-dev CLI、commands、agents、plugins、project-template、OpenSpec 與 framework 文件。
```
ValorVie/ai-dev-skills
```
：第一方 skill content、skill tests、collection README 與 CHANGELOG。

跨 repository 變更要分開檢查、分開提交。不得把 skill content 複製回 framework repository，也不得把 ai-dev runtime 文件放進 skill 目錄冒充 self-contained content。

First confirm which repository the changes belong to:

```
ValorVie/custom-skills
```
: Documentation for ai-dev CLI, commands, agents, plugins, project-template, OpenSpec, and framework.
```
ValorVie/ai-dev-skills
```
: First-party skill content, skill tests, collection README, and CHANGELOG.

Cross-repository changes should be checked and submitted separately. Do not copy skill content back to the framework repository, nor place ai-dev runtime files in skill directories to impersonate self-contained content.

Workflow Overview

Phase 1: 變更收集 → Phase 2: 變更分類 → Phase 3: 文件探索 → Phase 4: 影響分析 → Phase 5: 文件更新 → Phase 6: 驗證

Phase 1: Change Collection → Phase 2: Change Classification → Phase 3: Documentation Exploration → Phase 4: Impact Analysis → Phase 5: Documentation Update → Phase 6: Verification

Phase 1: 變更收集

Phase 1: Change Collection

Step 1.1: 確認分析範圍

Step 1.1: Confirm Analysis Scope

若使用者未指定範圍，使用 AskUserQuestion 詢問：

問題：您希望分析多少個最近的 commits？
選項：
- 最近 1 個 commit（預設）
- 最近 5 個 commits
- 最近 10 個 commits
- 自訂範圍（輸入 commit hash 或分支比較）

If the user does not specify a scope, use AskUserQuestion to inquire:

Question: How many recent commits would you like to analyze?
Options:
- Recent 1 commit (default)
- Recent 5 commits
- Recent 10 commits
- Custom scope (enter commit hash or branch comparison)

Step 1.2: 收集變更資料

Step 1.2: Collect Change Data

根據使用者選擇執行：

bash

undefined

Execute based on user selection:

bash

undefined

查看最近 N 個 commits

git log --oneline -N

查看變更的檔案

git diff --name-only HEAD~N

查看詳細變更摘要

git log --stat HEAD~N..HEAD


**替代方案（比較分支）：**
```bash
git diff --name-only main...HEAD
git log --oneline main...HEAD

git log --stat HEAD~N..HEAD


**Alternative (branch comparison):**
```bash
git diff --name-only main...HEAD
git log --oneline main...HEAD

Step 1.3: 整理變更清單

Step 1.3: Organize Change List

輸出格式：

markdown

undefined

Output format:

markdown

undefined

變更摘要

Change Summary

分析範圍: HEAD~5..HEAD (5 commits)

Analysis Scope: HEAD~5..HEAD (5 commits)

變更的檔案

Changed Files

plugins/ecc-hooks/README.md
plugins/ecc-hooks/hooks/hooks.json
openspec/changes/xxx/tasks.md
...

plugins/ecc-hooks/README.md
plugins/ecc-hooks/hooks/hooks.json
openspec/changes/xxx/tasks.md
...

Commit 摘要

Commit Summary

abc1234: feat: 新增 PHP hooks 支援
def5678: fix: 修正格式化問題

---

abc1234: feat: Add PHP hooks support
def5678: fix: Fix formatting issues

---

Phase 2: 變更分類

Phase 2: Change Classification

Step 2.1: 自動識別變更類型

Step 2.1: Automatically Identify Change Types

根據變更的檔案路徑和內容，識別變更類型：

檔案路徑模式	變更類型
`skills/*/.md`	`ai-dev-skills` repository 的 Skill 變更
`agents/*/.md`	Agent 變更
`commands/*/.md`	Command 變更
`plugins/*/`	Plugin 變更
`script/*/.py`	CLI 功能變更
`pyproject.toml` (version)	版本發布
`openspec/specs/*/`	Spec 變更
`upstream/*/`	上游整合
`sources/*/`	資源整合
`docs/*/`	文件變更（可能需要交叉更新）
`.standards/*/`	標準規範變更

Identify change types based on file paths and content:

File Path Pattern	Change Type
`skills/*/.md`	Skill change in `ai-dev-skills` repository
`agents/*/.md`	Agent change
`commands/*/.md`	Command change
`plugins/*/`	Plugin change
`script/*/.py`	CLI feature change
`pyproject.toml` (version)	Version release
`openspec/specs/*/`	Spec change
`upstream/*/`	Upstream integration
`sources/*/`	Resource integration
`docs/*/`	Documentation change (cross-update may be required)
`.standards/*/`	Standard specification change

Step 2.2: 提取關鍵字

Step 2.2: Extract Keywords

從變更中提取關鍵字用於後續文件搜尋：

從檔案名稱提取：
```
ecc-hooks
```
→ 搜尋關鍵字
從 commit message 提取：
```
新增 PHP hooks
```
→
```
PHP
```
,
```
hooks
```
從新增/修改的內容提取：function names, class names, feature names

Extract keywords from changes for subsequent documentation search:

Extract from file names:
```
ecc-hooks
```
→ search keyword
Extract from commit messages:
```
Add PHP hooks
```
→
```
PHP
```
,
```
hooks
```
Extract from added/modified content: function names, class names, feature names

Step 2.3: 輸出分類結果

Step 2.3: Output Classification Results

markdown

undefined

markdown

undefined

變更分類

Change Classification

類型	數量	關鍵項目
Plugin 變更	3	ecc-hooks
CLI 變更	1	derive-tests
Spec 變更	2	hook-testing, code-quality-hooks

提取的關鍵字:

ecc-hooks

PHP

hooks

code-quality

testing

---

Type	Count	Key Items
Plugin Change	3	ecc-hooks
CLI Change	1	derive-tests
Spec Change	2	hook-testing, code-quality-hooks

Extracted Keywords:

ecc-hooks

PHP

hooks

code-quality

testing

---

Phase 3: 文件探索

Phase 3: Documentation Exploration

Step 3.1: 優先檢查核心文件

Step 3.1: Prioritize Checking Core Documentation

必檢文件（依優先順序）：

```
CHANGELOG.md
```
- 版本歷史（幾乎所有變更都需要）
```
README.md
```
- 專案總覽
```
openspec/config.yaml
```
- 專案上下文（舊版為
```
openspec/project.md
```
，若存在也應檢查）
```
docs/**/*.md
```
- 文件資料夾

Mandatory files (in priority order):

```
CHANGELOG.md
```
- Version history (required for almost all changes)
```
README.md
```
- Project overview
```
openspec/config.yaml
```
- Project context (legacy version is
```
openspec/project.md
```
, check if exists)
```
docs/**/*.md
```
- Documentation folder

Step 3.2: 使用關鍵字搜尋相關文件

Step 3.2: Search Related Documentation Using Keywords

對每個提取的關鍵字，搜尋專案中的相關文件：

bash

undefined

For each extracted keyword, search for related files in the project:

bash

undefined

搜尋檔案名稱包含關鍵字

find . -name "keyword" -type f

搜尋檔案內容包含關鍵字

grep -rl "keyword" --include="*.md" .

搜尋 README 文件

find . -name "README.md" -type f


**使用 Grep 工具搜尋：**
- 搜尋 `ecc-hooks` 在所有 `.md` 文件中的出現
- 搜尋 `PHP` 在文件中的相關說明
- 搜尋功能名稱在哪些文件有記錄

find . -name "README.md" -type f


**Search using Grep tool:**
- Search for occurrences of `ecc-hooks` in all `.md` files
- Search for relevant descriptions of `PHP` in documentation
- Search which files record feature names

Step 3.3: 建立文件關聯圖

Step 3.3: Build Documentation Association Map

markdown

undefined

markdown

undefined

文件關聯分析

Documentation Association Analysis

關鍵字:

ecc-hooks

Keyword:

ecc-hooks

找到相關文件：

```
README.md
```
(Line 599-627: Claude Code Plugin 區塊)
```
plugins/ecc-hooks/README.md
```
(主要文件)
```
docs/AI開發環境設定指南.md
```
(Line 514-541: Plugin 安裝說明)
```
CHANGELOG.md
```
(Line 136-138: 0.9.7 版本記錄)

Found related files:

```
README.md
```
(Line 599-627: Claude Code Plugin section)
```
plugins/ecc-hooks/README.md
```
(Main documentation)
```
docs/AI開發環境設定指南.md
```
(Line 514-541: Plugin installation instructions)
```
CHANGELOG.md
```
(Line 136-138: Version 0.9.7 record)

關鍵字:

PHP

Keyword:

PHP

找到相關文件：

docs/dev-guide/workflow/CODE-QUALITY-TOOLS.md

(PHP 工具安裝)

```
plugins/ecc-hooks/README.md
```
(PHP formatting hooks)

---

Found related files:

docs/dev-guide/workflow/CODE-QUALITY-TOOLS.md

(PHP tool installation)

```
plugins/ecc-hooks/README.md
```
(PHP formatting hooks)

---

Phase 4: 影響分析

Phase 4: Impact Analysis

Step 4.1: 對照變更類型與文件

Step 4.1: Map Change Types to Documentation

使用以下對照表確定需要更新的文件：

Use the following mapping table to determine which files need updates:

Plugin 變更

Plugin Changes

文件	更新內容	必要性
`CHANGELOG.md`	新增/修改項目	必要
`plugins/<name>/README.md`	功能說明、安裝方式	必要
`README.md`	若涉及使用方式變更	視情況
`docs/AI開發環境設定指南.md`	若涉及安裝流程	視情況

File	Update Content	Necessity
`CHANGELOG.md`	Add/modify entries	Required
`plugins/<name>/README.md`	Feature description, installation method	Required
`README.md`	If usage changes are involved	As needed
`docs/AI開發環境設定指南.md`	If installation process is involved	As needed

Skill 變更

Skill Changes

文件	更新內容	必要性
`ai-dev-skills/CHANGELOG.md`	新增或修改項目	必要
`ai-dev-skills/README.md`	skill 清單、安裝方式或 boundary	視情況
`custom-skills/upstream/npx-skills.yaml`	只有 baseline 採用清單改變時更新	視情況

File	Update Content	Necessity
`ai-dev-skills/CHANGELOG.md`	Add or modify entries	Required
`ai-dev-skills/README.md`	Skill list, installation method, or boundary	As needed
`custom-skills/upstream/npx-skills.yaml`	Update only when baseline adoption list changes	As needed

Agent 變更

Agent Changes

文件	更新內容	必要性
`CHANGELOG.md`	新增項目	必要
`agents/claude/README.md`	Agent 清單表格	必要
`docs/Skill-Command-Agent差異說明.md`	「附錄：內建 Agents 清單」	必要

File	Update Content	Necessity
`CHANGELOG.md`	Add entries	Required
`agents/claude/README.md`	Agent list table	Required
`docs/Skill-Command-Agent差異說明.md`	"Appendix: Built-in Agents List"	Required

Command 變更

Command Changes

文件	更新內容	必要性
`CHANGELOG.md`	新增項目	必要
`commands/claude/README.md`	Command 清單表格	必要

File	Update Content	Necessity
`CHANGELOG.md`	Add entries	Required
`commands/claude/README.md`	Command list table	Required

CLI 功能變更

CLI Feature Changes

文件	更新內容	必要性
`CHANGELOG.md`	新增/修改項目	必要
`README.md`	指令說明、參數表格	必要

File	Update Content	Necessity
`CHANGELOG.md`	Add/modify entries	Required
`README.md`	Command instructions, parameter tables	Required

版本發布

Version Release

文件	更新內容	必要性
`pyproject.toml`	version 欄位	必要
`CHANGELOG.md`	日期、版本號	必要
`README.md`	確認功能說明	視情況

File	Update Content	Necessity
`pyproject.toml`	Version field	Required
`CHANGELOG.md`	Date, version number	Required
`README.md`	Verify feature descriptions	As needed

Step 4.2: 版本一致性檢查

Step 4.2: Version Consistency Check

檢查以下位置的版本號是否一致：

```
pyproject.toml
```
→
```
version
```
```
plugins/<name>/plugin.json
```
→
```
version
```
```
plugins/<name>/package.json
```
→
```
version
```
（如有）

Check if version numbers are consistent in the following locations:

```
pyproject.toml
```
→
```
version
```
```
plugins/<name>/plugin.json
```
→
```
version
```
```
plugins/<name>/package.json
```
→
```
version
```
(if exists)

Step 4.3: 生成影響報告

Step 4.3: Generate Impact Report

markdown

undefined

markdown

undefined

影響分析報告

Impact Analysis Report

需要更新的文件

Files Needing Updates

文件	原因	優先級	狀態
`CHANGELOG.md`	新增 ecc-hooks 測試框架	P1	⬜ 待更新
`plugins/ecc-hooks/package.json`	版本同步 (1.0.0 → 1.1.0)	P1	⬜ 待更新
`README.md`	功能無變更	-	✅ 無需更新
`docs/dev-guide/workflow/CODE-QUALITY-TOOLS.md`	功能無變更	-	✅ 無需更新

File	Reason	Priority	Status
`CHANGELOG.md`	Add ecc-hooks testing framework	P1	⬜ Pending update
`plugins/ecc-hooks/package.json`	Version synchronization (1.0.0 → 1.1.0)	P1	⬜ Pending update
`README.md`	No feature changes	-	✅ No update needed
`docs/dev-guide/workflow/CODE-QUALITY-TOOLS.md`	No feature changes	-	✅ No update needed

版本一致性

Version Consistency

```
pyproject.toml
```
: 1.0.4
```
plugins/ecc-hooks/plugin.json
```
: 1.1.0
```
plugins/ecc-hooks/package.json
```
: 1.0.0 ⚠️ 不一致

---

```
pyproject.toml
```
: 1.0.4
```
plugins/ecc-hooks/plugin.json
```
: 1.1.0
```
plugins/ecc-hooks/package.json
```
: 1.0.0 ⚠️ Inconsistent

---

Phase 5: 文件更新

Phase 5: Documentation Update

Step 5.1: 依優先級更新文件

Step 5.1: Update Files by Priority

P1 - 必要更新：先處理 CHANGELOG.md 和版本同步
P2 - 重要更新：功能文件、README
P3 - 可選更新：參考文件、次要文件

P1 - Required Updates: First handle CHANGELOG.md and version synchronization
P2 - Important Updates: Feature documentation, README
P3 - Optional Updates: Reference documentation, secondary files

Step 5.2: 更新前必須讀取

Step 5.2: Must Read Before Updating

重要：更新任何文件前，必須先使用 Read 工具讀取該文件，確認：

目前內容
需要插入/修改的位置
格式規範

Important: Before updating any file, you must first use the Read tool to read the file and confirm:

Current content
Position to insert/modify
Format specifications

Step 5.3: 遵循格式規範

Step 5.3: Follow Format Specifications

CHANGELOG 格式

CHANGELOG Format

markdown

undefined

markdown

undefined

[Unreleased]

Added

功能類別
- 詳細描述
- 子項目說明

Feature Category
- Detailed description
- Sub-item description

Changed

Breaking Change 類別
- 變更描述
- 遷移指引

Breaking Change Category
- Change description
- Migration guide

Fixed

修復描述

Fix description

Removed

移除項目描述

undefined

Removal description

undefined

版本歷史表格格式

Version History Table Format

markdown

undefined

markdown

undefined

Version History

Version	Date	Changes
1.1.0	2026-01-28	Added feature X

---

Version	Date	Changes
1.1.0	2026-01-28	Added feature X

---

Phase 6: 驗證

Phase 6: Verification

Step 6.1: 驗證清單

Step 6.1: Verification Checklist

完成更新後，逐項確認：

markdown

undefined

After completing updates, confirm item by item:

markdown

undefined

更新驗證清單

Update Verification Checklist

文件更新狀態

Documentation Update Status

```
CHANGELOG.md
```
- 已新增 ecc-hooks 測試框架記錄
```
plugins/ecc-hooks/package.json
```
- 版本同步至 1.1.0
```
README.md
```
- 無需更新

```
CHANGELOG.md
```
- Added ecc-hooks testing framework record
```
plugins/ecc-hooks/package.json
```
- Version synchronized to 1.1.0
```
README.md
```
- No update needed

版本一致性（更新後）

Version Consistency (After Update)

位置	版本	狀態
`pyproject.toml`	1.0.4	✓
`plugins/ecc-hooks/plugin.json`	1.1.0	✓
`plugins/ecc-hooks/package.json`	1.1.0	✓

Location	Version	Status
`pyproject.toml`	1.0.4	✓
`plugins/ecc-hooks/plugin.json`	1.1.0	✓
`plugins/ecc-hooks/package.json`	1.1.0	✓

交叉引用

Cross-Reference

Step 6.2: 輸出最終摘要

Step 6.2: Output Final Summary

markdown

undefined

markdown

undefined

文件更新摘要

Documentation Update Summary

分析範圍: HEAD~5..HEAD

Analysis Scope: HEAD~5..HEAD

已更新

Updated Files

文件	更新內容
`CHANGELOG.md`	新增 ECC Hooks Plugin 測試框架記錄
`plugins/ecc-hooks/package.json`	版本同步至 1.1.0

File	Update Content
`CHANGELOG.md`	Added ECC Hooks Plugin testing framework record
`plugins/ecc-hooks/package.json`	Version synchronized to 1.1.0

無需更新

No Updates Needed

文件	原因
`README.md`	主要功能無變更
`docs/*`	與此次變更無關

File	Reason
`README.md`	No major feature changes
`docs/*`	Unrelated to this change

版本一致性

Version Consistency

✓ 所有版本號已同步

---

✓ All version numbers are synchronized

---

快速參考

Quick Reference

常見遺漏提醒

Common Omission Reminders

新增 Agent 時

When Adding an Agent

⚠️
```
docs/Skill-Command-Agent差異說明.md
```
- 「附錄：內建 Agents 清單」
⚠️
```
agents/claude/README.md
```
- Built-in Agents 表格

⚠️
```
docs/Skill-Command-Agent差異說明.md
```
- "Appendix: Built-in Agents List"
⚠️
```
agents/claude/README.md
```
- Built-in Agents table

新增 Command 系列時

When Adding a Command Series

⚠️
```
commands/claude/README.md
```
- 需要新增完整的類別區塊

⚠️
```
commands/claude/README.md
```
- Need to add complete category sections

上游整合時

When Integrating Upstream

⚠️
```
upstream/README.md
```
- 「整合決定記錄」區塊

⚠️
```
upstream/README.md
```
- "Integration Decision Record" section

Plugin 變更時

When Changing a Plugin

⚠️ 版本號同步（plugin.json 與 package.json）

⚠️ Version number synchronization (plugin.json and package.json)

語言規範

Language Specifications

所有文件使用繁體中文，保留英文技術術語：

Skill, Command, Agent, Hook, Plugin
CLI, TUI, MCP, API
Git, GitHub, upstream

All documentation uses Traditional Chinese, with English technical terms retained:

Skill, Command, Agent, Hook, Plugin
CLI, TUI, MCP, API
Git, GitHub, upstream

參數說明

Parameter Description

skill 可接受以下參數：

參數	說明	範例
無參數	詢問分析範圍	`/doc-updater`
`N`	分析最近 N 個 commits	`/doc-updater 5`
`--since <ref>`	從指定 ref 開始分析	`/doc-updater --since v1.0.0`
`--check`	僅檢查，不執行更新	`/doc-updater --check`

This skill accepts the following parameters:

Parameter	Description	Example
No parameter	Ask for analysis scope	`/doc-updater`
`N`	Analyze recent N commits	`/doc-updater 5`
`--since <ref>`	Analyze from specified ref	`/doc-updater --since v1.0.0`
`--check`	Only check, do not perform updates	`/doc-updater --check`