docs-sync-checker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Sync Checker Skill

Operator Context

操作者背景

This skill operates as an operator for documentation synchronization workflows, configuring Claude's behavior for automated drift detection between filesystem tools and their README entries. It implements deterministic scanning and comparison -- no AI judgment on content quality, only presence/absence/version verification.

The 4-phase workflow (Scan, Cross-Reference, Detect, Report) ensures systematic coverage. Each phase has a gate that must pass before proceeding. The skill produces a sync score (percentage of tools properly documented) and actionable fix suggestions for every detected issue.

该Skill作为文档同步工作流的操作者，配置Claude的行为以自动检测文件系统工具与其README条目之间的漂移。它实现了确定性扫描和比较——不对内容质量做AI判断，仅验证存在性/缺失性/版本一致性。

四阶段工作流（扫描、交叉引用、检测、报告）确保系统性覆盖。每个阶段都设有必须通过的检查门限。该Skill会生成同步分数（文档记录正确的工具占比），并为每个检测到的问题提供可执行的修复建议。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
Over-Engineering Prevention: Only scan, compare, and report. No speculative features
Deterministic Scanning: File existence, YAML parsing, and markdown extraction must be deterministic
Documentation File Locations: Check specific files: skills/README.md, agents/README.md, commands/README.md, README.md, docs/REFERENCE.md
Sync Rules: Skills in skills/README.md, agents in agents/README.md, commands in commands/README.md

CLAUDE.md 合规性：执行前读取并遵循仓库的CLAUDE.md
避免过度设计：仅执行扫描、比较和报告，不添加推测性功能
确定性扫描：文件存在性、YAML解析和Markdown提取必须是确定性的
文档文件位置：检查指定文件：skills/README.md、agents/README.md、commands/README.md、README.md、docs/REFERENCE.md
同步规则：Skills对应skills/README.md，Agents对应agents/README.md，Commands对应commands/README.md

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则开启）

Concise Reporting: Report facts without self-congratulation; show data, not descriptions
Temporary File Cleanup: Remove helper scripts and debug outputs at task completion
Stale Entry Detection: Flag documented tools that no longer exist in the filesystem
Version Mismatch Detection: Compare YAML frontmatter versions with documented versions
Severity Assignment: HIGH for missing entries, MEDIUM for stale entries, LOW for version mismatches

简洁报告：仅报告事实，不添加自夸内容；展示数据而非描述
临时文件清理：任务完成后移除辅助脚本和调试输出
过期条目检测：标记文件系统中已不存在但仍在文档中记录的工具
版本不匹配检测：比较YAML前置元数据版本与文档中记录的版本
严重程度分配：缺失条目为高优先级，过期条目为中优先级，版本不匹配为低优先级

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则关闭）

Auto-Fix Mode: Automatically add missing documentation entries (--auto-fix)
Strict Mode: Exit with error code if sync issues found (--strict)
JSON Output: Machine-readable report for CI/CD pipelines (--format json)

自动修复模式：自动添加缺失的文档条目（需使用--auto-fix参数）
严格模式：若发现同步问题则返回错误码退出（需使用--strict参数）
JSON输出：生成机器可读的报告，用于CI/CD流水线（需使用--format json参数）

What This Skill CAN Do

该Skill可完成的任务

Discover all skills (skills//SKILL.md), agents (agents/.md), and commands (commands/**/*.md)
Parse YAML frontmatter and extract name, description, version fields
Parse markdown tables and lists from README files using deterministic parsing
Detect missing entries (tool exists in filesystem, not documented in README)
Detect stale entries (documented in README, tool no longer in filesystem)
Detect version mismatches (YAML version differs from documented version)
Generate actionable sync reports with exact suggested fixes (markdown rows to add/remove)
Handle namespaced commands (commands/code/cleanup.md -> /code cleanup)
Calculate sync score as percentage of tools properly documented
Support strict mode for CI/CD integration (exit code 1 on issues)

发现仓库文件系统中所有的Skills（skills//SKILL.md）、Agents（agents/.md）和Commands（commands/**/*.md）
解析YAML前置元数据，提取name、description、version字段
通过确定性解析从README文件中提取Markdown表格和列表
检测缺失条目（文件系统中存在但未在README中记录的工具）
检测过期条目（README中记录但文件系统中已不存在的工具）
检测版本不匹配（YAML版本与文档中记录的版本不一致）
生成包含可执行修复建议的同步报告（需添加/移除的Markdown行内容）
处理命名空间化的Commands（如commands/code/cleanup.md 对应 /code cleanup）
计算同步分数（文档记录正确的工具占比）
支持与CI/CD集成的严格模式（存在问题时返回退出码1）

What This Skill CANNOT Do

该Skill不可完成的任务

Judge whether descriptions are accurate or helpful (presence only, not quality)
Generate or improve documentation content (uses YAML description verbatim)
Resolve markdown merge conflicts in documentation files
Validate cross-references or internal links between documents
Track when documentation drift occurred (point-in-time snapshot only)
Fix semantic inconsistencies between descriptions in different files
Automatically fix documentation without human review (auto-fix is experimental, requires explicit opt-in)
Reason: This skill is deterministic scanning and comparison. Content generation and quality assessment require different skills.

判断描述是否准确或有用（仅验证存在性，不评估质量）
生成或优化文档内容（直接使用YAML中的描述内容）
解决文档文件中的Markdown合并冲突
验证文档之间的交叉引用或内部链接
追踪文档漂移发生的时间（仅提供即时快照）
修复不同文件中描述的语义不一致问题
无需人工审核自动修复文档（自动修复为实验性功能，需显式开启）
原因：该Skill仅做确定性扫描和比较。内容生成和质量评估需要其他Skill支持。

Instructions

操作指南

Phase 1: SCAN

阶段1：扫描

Goal: Discover all skills, agents, and commands in the repository filesystem.

Step 1: Run the scan script

bash

python3 skills/docs-sync-checker/scripts/scan_tools.py --repo-root $HOME/claude-code-toolkit

Step 2: Validate discovery results

For each tool type, verify:

Skills (

skills/*/SKILL.md

File has opening
```
---
```
and closing
```
---
```
YAML delimiters
YAML contains
```
name
```
,
```
description
```
, and
```
version
```
fields

name

field matches directory name (e.g.,

skills/code-linting/

has

name: code-linting

)

Agents (

agents/*.md

File has valid YAML frontmatter with
```
name
```
field
Filename (without .md) matches YAML
```
name
```
value

Commands (

commands/**/*.md

File exists as markdown in commands/ directory
Namespaced commands in subdirectories (e.g.,
```
commands/code/cleanup.md
```
) are detected

Step 3: Count and verify

markdown

undefined

目标：发现仓库文件系统中所有的Skills、Agents和Commands。

步骤1：运行扫描脚本

bash

python3 skills/docs-sync-checker/scripts/scan_tools.py --repo-root $HOME/claude-code-toolkit

步骤2：验证发现结果

针对每种工具类型，验证：

Skills（skills/*/SKILL.md）：

文件包含开头和结尾的
```
---
```
YAML分隔符
YAML中包含
```
name
```
、
```
description
```
和
```
version
```
字段
```
name
```
字段与目录名称匹配（例如
```
skills/code-linting/
```
对应
```
name: code-linting
```
）

Agents（agents/*.md）：

文件包含带有
```
name
```
字段的有效YAML前置元数据
文件名（不含.md后缀）与YAML中的
```
name
```
值匹配

Commands（commands/**/*.md）：

文件以Markdown格式存在于commands/目录下
可检测到子目录中的命名空间化Commands（如commands/code/cleanup.md）

步骤3：统计并验证

markdown

undefined

Scan Results

扫描结果

Skills found: [N] Agents found: [N] Commands found: [N] YAML errors: [N] (must be 0 to proceed)


**Gate**: All tools discovered, all YAML valid, counts >0 for each type. Do NOT proceed until gate passes.

已发现Skills：[数量] 已发现Agents：[数量] 已发现Commands：[数量] YAML错误：[数量]（必须为0才能继续）


**检查门限**：所有工具已被发现，所有YAML均有效，每种类型的数量大于0。未通过门限前请勿继续。

Phase 2: CROSS-REFERENCE

阶段2：交叉引用

Goal: Extract documented tools from README files and compare with discovered tools.

Step 1: Run the documentation parser

bash

python3 skills/docs-sync-checker/scripts/parse_docs.py --repo-root $HOME/claude-code-toolkit --scan-results /tmp/scan_results.json

Step 2: Parse each documentation file

File	Format	What to Extract
`skills/README.md`	Markdown table	Name, Description, Command, Hook columns
`agents/README.md`	Table or list	Name, Description fields
`commands/README.md`	Markdown list	/command-name - Description items
`README.md`	Inline references	Pattern-match `skill: X` , `/command` , `agent-name`
`docs/REFERENCE.md`	Section headers	`### tool-name` headers with descriptions

Step 3: Build documented-tools registry

For each documentation file, collect the set of tool names found. This creates a mapping of

{file -> [tool_names]}

that Phase 3 will compare against the filesystem scan.

Step 4: Verify parse completeness

All 5 documentation files found and parsed (warn if any missing)
No parse errors on table/list structures
Tool names extracted from each file

Gate: All documentation files parsed without errors. Do NOT proceed until gate passes.

目标：从README文件中提取已记录的工具，并与发现的工具进行比较。

步骤1：运行文档解析器

bash

python3 skills/docs-sync-checker/scripts/parse_docs.py --repo-root $HOME/claude-code-toolkit --scan-results /tmp/scan_results.json

步骤2：解析每个文档文件

文件	格式	提取内容
`skills/README.md`	Markdown表格	Name、Description、Command、Hook列
`agents/README.md`	表格或列表	Name、Description字段
`commands/README.md`	Markdown列表	/command-name - Description 条目
`README.md`	内联引用	匹配 `skill: X` 、 `/command` 、 `agent-name` 模式
`docs/REFERENCE.md`	章节标题	`### tool-name` 标题及其描述

步骤3：构建已记录工具注册表

针对每个文档文件，收集已发现的工具名称集合。这将生成一个

{文件 -> [工具名称]}

的映射，供阶段3与文件系统扫描结果进行比较。

步骤4：验证解析完整性

所有5个文档文件均已找到并解析（若有缺失则发出警告）
表格/列表结构解析无错误
已从每个文件中提取工具名称

检查门限：所有文档文件均已成功解析，无错误。未通过门限前请勿继续。

Phase 3: DETECT

阶段3：检测

Goal: Compare discovered tools with documented tools to identify drift.

Step 1: Compute set differences

For each tool type and its primary documentation file:

missing = filesystem_tools - documented_tools

(tools that exist but are not documented)

stale = documented_tools - filesystem_tools

(documented tools that no longer exist)

Step 2: Check version consistency

For tools that appear in both sets, compare:

YAML
```
version
```
field vs. documented version (if version is documented)
Flag mismatches where YAML is authoritative source of truth

Step 3: Categorize and assign severity

Category	Condition	Severity
Missing Entry	Tool in filesystem, not in primary README	HIGH
Stale Entry	Tool in README, not in filesystem	MEDIUM
Version Mismatch	YAML version differs from documented	LOW
Incomplete Entry	Documentation missing required fields	LOW

Step 4: Record issue details

For each issue, capture: tool type, tool name, tool path, affected documentation file(s), severity, and suggested fix action.

Gate: All issues categorized with severity. Do NOT proceed until gate passes.

目标：比较发现的工具与已记录的工具，识别漂移情况。

步骤1：计算集合差异

针对每种工具类型及其对应的主文档文件：

missing = 文件系统工具 - 已记录工具

（存在但未记录的工具）

stale = 已记录工具 - 文件系统工具

（已记录但不存在的工具）

步骤2：检查版本一致性

对于同时存在于两个集合中的工具，比较：

YAML中的
```
version
```
字段与文档中记录的版本（若文档中记录了版本）
标记不匹配情况，其中YAML为权威数据源

步骤3：分类并分配严重程度

分类	条件	严重程度
缺失条目	文件系统中存在但主README中未记录	高
过期条目	README中记录但文件系统中不存在	中
版本不匹配	YAML版本与文档中记录的版本不一致	低
不完整条目	文档中缺失必填字段	低

步骤4：记录问题详情

针对每个问题，记录：工具类型、工具名称、工具路径、受影响的文档文件、严重程度以及建议的修复操作。

检查门限：所有问题均已分类并分配严重程度。未通过门限前请勿继续。

Phase 4: REPORT

阶段4：报告

Goal: Generate human-readable report with actionable fix suggestions.

Step 1: Run the report generator

bash

python3 skills/docs-sync-checker/scripts/generate_report.py --issues /tmp/issues.json --output /tmp/sync-report.md

Step 2: Verify report structure

Report must include these sections:

Summary -- Total tools, issue counts by severity, sync score

sync_score = (total_tools - total_issues) / total_tools * 100

HIGH Priority: Missing Entries -- For each missing tool, provide the exact markdown row/item to add to the appropriate README file
MEDIUM Priority: Stale Entries -- For each stale tool, identify the file and line to remove
LOW Priority: Version Mismatches -- For each mismatch, show YAML version (authoritative) vs. documented version
Files Checked -- List each documentation file with count of tools parsed from it

Step 3: Validate actionability

Every issue in the report must have a concrete suggested fix. No issue should say "review manually" without specifying what to review and where.

Step 4: Report format for missing entries

For each missing skill, generate a suggested table row:

markdown

| skill-name | Description from YAML | `skill: skill-name` | - |

For each missing agent, generate a suggested table row:

markdown

| agent-name | Description from YAML |

For each missing command, generate a suggested list item:

markdown

- `/command-name` - Description from command file

Gate: Report generated with actionable suggestions for every issue.

目标：生成包含可执行修复建议的人类可读报告。

步骤1：运行报告生成器

bash

python3 skills/docs-sync-checker/scripts/generate_report.py --issues /tmp/issues.json --output /tmp/sync-report.md

步骤2：验证报告结构

报告必须包含以下章节：

摘要 -- 工具总数、各严重程度的问题数量、同步分数
```
sync_score = (总工具数 - 总问题数) / 总工具数 * 100
```
高优先级：缺失条目 -- 针对每个缺失的工具，提供需添加到对应README文件的精确Markdown行内容
中优先级：过期条目 -- 针对每个过期的工具，指出需移除的文件和行
低优先级：版本不匹配 -- 针对每个不匹配情况，展示YAML版本（权威值）与文档中记录的版本
已检查文件 -- 列出每个已检查的文档文件及其从中解析出的工具数量

步骤3：验证可执行性

报告中的每个问题都必须包含具体的修复建议。任何问题都不应仅提示「手动检查」而不说明检查内容和位置。

步骤4：缺失条目的报告格式

针对每个缺失的Skill，生成建议的表格行：

markdown

| skill-name | YAML中的描述 | `skill: skill-name` | - |

针对每个缺失的Agent，生成建议的表格行：

markdown

| agent-name | YAML中的描述 |

针对每个缺失的Command，生成建议的列表项：

markdown

- `/command-name` - 命令文件中的描述

检查门限：报告已生成，且每个问题都包含可执行的修复建议。

Examples

示例

Example 1: New Skill Missing from README

示例1：新Skill未添加到README

User created

skills/my-new-skill/SKILL.md

but forgot to update

skills/README.md

. Actions:

SCAN discovers
```
my-new-skill
```
in filesystem
CROSS-REFERENCE parses skills/README.md, does not find
```
my-new-skill
```
DETECT flags as HIGH severity missing entry
REPORT suggests exact table row to add to skills/README.md

用户创建了

skills/my-new-skill/SKILL.md

但忘记更新

skills/README.md

。操作流程：

扫描阶段在文件系统中发现
```
my-new-skill
```
交叉引用阶段解析skills/README.md，未找到
```
my-new-skill
```
检测阶段标记为高优先级缺失条目
报告阶段建议添加到skills/README.md的精确表格行内容

Example 2: Removed Agent Still Documented

示例2：已移除的Agent仍在文档中

User deleted

agents/old-agent.md

but

agents/README.md

still lists it. Actions:

SCAN does not find
```
old-agent
```
in filesystem
CROSS-REFERENCE finds
```
old-agent
```
in agents/README.md
DETECT flags as MEDIUM severity stale entry
REPORT suggests removing the row from agents/README.md

用户删除了

agents/old-agent.md

但

agents/README.md

中仍有记录。操作流程：

扫描阶段在文件系统中未找到
```
old-agent
```
交叉引用阶段在agents/README.md中找到
```
old-agent
```
检测阶段标记为中优先级过期条目
报告阶段建议从agents/README.md中移除对应行

Example 3: Version Bump Without Doc Update

示例3：版本更新但未同步文档

User updated

version: 2.0.0

skills/code-linting/SKILL.md

but

docs/REFERENCE.md

still shows

Version: 1.5.0

. Actions:

SCAN reads YAML version as 2.0.0
CROSS-REFERENCE reads documented version as 1.5.0 from docs/REFERENCE.md
DETECT flags as LOW severity version mismatch
REPORT suggests updating version line in docs/REFERENCE.md to 2.0.0

用户更新了

skills/code-linting/SKILL.md

中的

version: 2.0.0

但

docs/REFERENCE.md

仍显示

Version: 1.5.0

。操作流程：

扫描阶段读取YAML版本为2.0.0
交叉引用阶段从docs/REFERENCE.md中读取到记录的版本为1.5.0
检测阶段标记为低优先级版本不匹配
报告阶段建议将docs/REFERENCE.md中的版本行更新为2.0.0

Example 4: Batch Changes After Refactor

示例4：重构后的批量变更

User created 3 new skills and deleted 2 old ones in a refactoring PR. Actions:

SCAN discovers 3 new skills in filesystem, does not find 2 removed skills
CROSS-REFERENCE finds 2 stale entries and 3 absent entries in skills/README.md
DETECT flags 3 HIGH (missing) + 2 MEDIUM (stale) issues
REPORT provides exact table rows to add and identifies rows to remove

用户在重构PR中创建了3个新Skill并删除了2个旧Skill。操作流程：

扫描阶段在文件系统中发现3个新Skill，未找到2个已移除的Skill
交叉引用阶段在skills/README.md中发现2个过期条目和3个缺失条目
检测阶段标记3个高优先级（缺失）和2个中优先级（过期）问题
报告阶段提供需添加的精确表格行内容，并指出需移除的行

Error Handling

错误处理

Error: "YAML Parse Error"

错误："YAML Parse Error"

Cause: Invalid frontmatter -- missing

---

delimiters, tabs instead of spaces, or missing required fields Solution:

Check file has opening
```
---
```
on line 1 and closing
```
---
```
after YAML block
Verify no tab characters in YAML (spaces only)
Confirm required fields present:
```
name
```
,
```
description
```
,
```
version
```
Validate manually:
```
head -20 {file_path}
```
and check syntax

原因：无效的前置元数据——缺少

---

分隔符、使用制表符而非空格、或缺失必填字段解决方案：

检查文件第一行是否有开头的
```
---
```
，YAML块末尾是否有结尾的
```
---
```
验证YAML中没有制表符（仅使用空格）
确认必填字段存在：
```
name
```
、
```
description
```
、
```
version
```
手动验证：执行
```
head -20 {file_path}
```
并检查语法

Error: "Documentation File Not Found"

错误："Documentation File Not Found"

Cause: Expected README file does not exist at expected path Solution:

Verify --repo-root path is correct
Check that skills/README.md, agents/README.md, commands/README.md exist
If file is legitimately missing, create a placeholder with the expected table/list header
Re-run scan after creating placeholder

原因：预期的README文件未在指定路径存在解决方案：

验证--repo-root路径是否正确
检查skills/README.md、agents/README.md、commands/README.md是否存在
如果文件确实缺失，创建包含预期表格/列表标题的占位文件
创建占位文件后重新运行扫描

Error: "No Tools Discovered"

错误："No Tools Discovered"

Cause: Wrong --repo-root path, empty directories, or no SKILL.md files Solution:

Verify the repo root path points to the correct repository
Confirm skills/, agents/, commands/ directories exist and are not empty
Check that skill directories contain SKILL.md (not just other files)
Run with --debug flag for verbose discovery output

原因：--repo-root路径错误、目录为空、或无SKILL.md文件解决方案：

验证仓库根路径指向正确的仓库
确认skills/、agents/、commands/目录存在且不为空
检查Skill目录中是否包含SKILL.md文件（而非仅其他文件）
使用--debug参数运行以获取详细的发现输出

Error: "Markdown Parse Error"

错误："Markdown Parse Error"

Cause: Table missing separator row, mismatched column counts, or malformed list items Solution:

Check table has header row, separator row (
```
|---|---|
```
), and data rows
Verify all rows have the same number of pipe-delimited columns
For lists, verify consistent format:
```
- /command - Description
```
See
```
references/markdown-formats.md
```
for complete format specifications

原因：表格缺少分隔行、列数不匹配、或列表项格式错误解决方案：

检查表格是否有标题行、分隔行（
```
|---|---|
```
）和数据行
验证所有行的竖线分隔列数一致
对于列表，验证格式一致：
```
- /command - Description
```
查看
```
references/markdown-formats.md
```
获取完整的格式规范

Anti-Patterns

反模式

Anti-Pattern 1: Creating Tools Without Documentation

反模式1：创建工具但不更新文档

What it looks like:

git commit -m "Add new skill"

without updating skills/README.md Why wrong: Documentation drifts from reality; users cannot discover the tool Do instead: Run docs-sync-checker before committing; add tool AND documentation in same commit

表现：执行

git commit -m "Add new skill"

但未更新skills/README.md 问题：文档与实际情况脱节；用户无法发现该工具 正确做法：提交前运行docs-sync-checker；在同一提交中添加工具和对应的文档

Anti-Pattern 2: Removing Tools, Leaving Documentation

反模式2：移除工具但保留文档

What it looks like:

rm -rf skills/old-skill

followed by commit, but README still lists it Why wrong: Users waste time trying to invoke non-existent tools; erodes trust in docs Do instead: Remove tool files AND documentation entries together in one commit

表现：执行

rm -rf skills/old-skill

后提交，但README中仍有记录问题：用户浪费时间尝试调用不存在的工具；降低文档可信度 正确做法：在同一提交中同时移除工具文件和文档中的对应条目

Anti-Pattern 3: Manual Edits Without Validation

反模式3：手动编辑后不验证

What it looks like: Hand-editing README tables without running sync checker afterward Why wrong: Typos in tool names create phantom entries (documented but non-existent) Do instead: Always validate with docs-sync-checker after manual documentation edits

表现：手动编辑README表格但未运行同步检查器问题：工具名称拼写错误会导致 phantom 条目（已记录但不存在） 正确做法：手动编辑文档后始终使用docs-sync-checker进行验证

Anti-Pattern 4: Ignoring Sync Failures in CI

反模式4：在CI中忽略同步失败

What it looks like:

continue-on-error: true

on the sync check step in GitHub Actions Why wrong: Documentation drift accumulates; the check becomes meaningless Do instead: Run with --strict and let the build fail; fix docs before merging

表现：在GitHub Actions的同步检查步骤中设置

continue-on-error: true

问题：文档漂移会不断累积；检查失去意义 正确做法：使用--strict模式，让构建失败；合并前修复文档问题

Anti-Pattern 5: Updating Version Without Syncing Documentation

反模式5：更新版本但不同步文档

What it looks like: Bumping

version: 2.0.0

in YAML frontmatter, committing without checking docs Why wrong: Version mismatch creates confusion about which version is deployed; users reference wrong version Do instead: Update YAML version, run sync checker, update all documentation locations in one commit

表现：更新YAML前置元数据中的

version: 2.0.0

后直接提交，未检查文档问题：版本不匹配会导致用户对已部署版本产生混淆；用户会参考错误的版本 正确做法：更新YAML版本后，运行同步检查器，在同一提交中更新所有相关文档位置

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

该Skill使用以下共享模式：

Anti-Rationalization - 防止找借口走捷径
Verification Checklist - 完成前检查

Domain-Specific Anti-Rationalization

领域特定的反合理化

Rationalization	Why It's Wrong	Required Action
"I'll update the README later"	Later never comes; drift accumulates	Update docs in the same commit
"It's just one missing entry"	One missing entry erodes trust in all docs	Fix immediately
"The sync score is still 90%"	90% means 1 in 10 tools is undocumented	Target 100%
"CI will catch it"	Only if CI is configured and not ignored	Verify locally first

合理化借口	问题所在	要求操作
"我稍后再更新README"	稍后往往变成永远；漂移不断累积	在同一提交中更新文档
"只是一个缺失的条目而已"	一个缺失条目会降低所有文档的可信度	立即修复
"同步分数仍有90%"	90%意味着每10个工具中就有1个未被记录	目标为100%
"CI会检测到的"	只有当CI已配置且未被忽略时才会生效	先在本地验证

Reference Files

参考文件

```
${CLAUDE_SKILL_DIR}/references/documentation-structure.md
```
: Documentation file matrix, required fields per location, cross-reference requirements
```
${CLAUDE_SKILL_DIR}/references/markdown-formats.md
```
: Expected table/list formats for each README file, parsing rules, common formatting errors
```
${CLAUDE_SKILL_DIR}/references/sync-rules.md
```
: Synchronization rules, severity levels, deprecation handling, namespace rules
```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: Before/after examples for adding, removing, updating, and batch documentation changes
```
${CLAUDE_SKILL_DIR}/references/integration-guide.md
```
: CI/CD setup, pre-commit hooks, auto-fix mode, JSON output, workflow integration

```
${CLAUDE_SKILL_DIR}/references/documentation-structure.md
```
：文档文件矩阵、各位置的必填字段、交叉引用要求
```
${CLAUDE_SKILL_DIR}/references/markdown-formats.md
```
：每个README文件的预期表格/列表格式、解析规则、常见格式错误
```
${CLAUDE_SKILL_DIR}/references/sync-rules.md
```
：同步规则、严重程度等级、弃用处理、命名空间规则
```
${CLAUDE_SKILL_DIR}/references/examples.md
```
：添加、移除、更新和批量文档变更的前后示例
```
${CLAUDE_SKILL_DIR}/references/integration-guide.md
```
：CI/CD设置、提交前钩子、自动修复模式、JSON输出、工作流集成