docs-sync

/docs:sync [OPTIONS]

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 docs-generate……
README 或 CLAUDE.md 中的技能、命令或 Agent 数量与目录中的实际内容不一致	根据代码生成新的 API 参考文档、重写 README 或编写 CHANGELOG 内容
新增了技能，但尚未列入目录表格	目录本身没有问题，只是需要编写新文档
文档中仍有已删除项目的过时条目	编写服务拆除检查清单（使用 docs-decommission）
重构后需要重新核对交叉引用和类别分组	将现有 Markdown 文档转换为适合打印的 PDF（使用 docs-latex）

扫描代码库中的技能、命令和 Agent，然后更新所有文档以反映当前状态。修正数量不符的问题，添加缺失条目，并移除过时引用。

用法

/docs:sync                        # Sync all documentation
/docs:sync --scope skills         # Only sync skill documentation
/docs:sync --scope commands       # Only sync command documentation
/docs:sync --scope agents         # Only sync agent documentation
/docs:sync --dry-run              # Show what would change without modifying
/docs:sync --verbose              # Show detailed scanning output

参数

• --scope <type> - 将同步范围限制为指定类型：skills、commands、agents 或 all（默认）
• --dry-run - 预览更改，不修改文件
• --verbose - 显示扫描过程的详细进度

执行

执行以下文档同步工作流：

步骤 1：发现代码库项目

1. 扫描源目录：

   # Skills
   find .claude/skills -name "SKILL.md" -type f
   
   # Commands
   find .claude/commands -name "*.md" -type f ! -name "CLAUDE.md"
   
   # Agents
   find .claude/agents -name "*.md" -type f
   

2. 提取每个项目的元数据：

   • 技能：解析 YAML frontmatter，获取 name 和 description
   • 命令：解析 frontmatter 中的 description，根据路径推断命名空间
   • Agent：解析 frontmatter，获取 name、description 和 tools

3. 解析现有文档：

   • .claude/skills/CLAUDE.md - 当前技能目录及其分类
   • .claude/skills/CLAUDE.md - 按命名空间划分的命令参考
   • 根目录 CLAUDE.md - 汇总数量和重点内容

步骤 2：分析差异

1. 比较实际内容与文档记录：

   • 查找目录中存在、但文档中缺失的项目（新增）
   • 查找文档中存在、但目录中缺失的项目（过时）
   • 检查数量是否一致

2. 对新增项目分类：

   对于技能，根据以下信息确定类别：

   • 名称模式：ux-*、git-*、python-* → 对应类别
   • 描述中的关键词：「无障碍」「测试」「基础设施」
   • 同一领域中相似的现有技能
   • 如无法确定，建议归入「未分类」以便人工审核

   对于可由用户调用的技能，根据目录名称确定命名空间：

   • skills/git-commit/SKILL.md → git: 命名空间
   • skills/handoffs/SKILL.md → 根级别

   对于 Agent，根据描述中的关键词确定所属领域

3. 确定需要更新的文档部分：

   • 数量模式：**N skills**、N total、(N skills)
   • 按类别／命名空间划分的列表部分
   • 汇总表格

步骤 3：应用更新

1. 更新文档中的数量：

   • 搜索类似 **63 skills** 或 63 specialized skills 的模式
   • 替换为准确数量
   • 更新类别数量，如 ### Core Development (9 skills)

2. 将新增项目添加到相应部分：

   技能目录格式：

   ### Category Name (N skills)
   - **skill-name** - Description from SKILL.md frontmatter
   

   命令表格格式：

   | Namespace | Commands | Purpose |
   | `/command` | Description | Usage context |
   

   Agent 清单格式：

   | Agent | Purpose | Key Tools |
   | **agent-name** | Description | Tool1, Tool2 |
   

3. 移除代码库中已不存在的过时条目

4. 更新交叉引用：

   • 「另请参阅」部分
   • 相关技能／命令列表

步骤 4：报告结果

生成更改摘要：

## Documentation Sync Report

### Skills
- ✅ Added N new skills to catalog
  - skill-name → Category Name
- ✅ Removed N stale skills
- ✅ Updated skill count: OLD → NEW

### Commands
- ✅ Added N new commands
  - /namespace:command → Description
- ✅ Updated command counts

### Agents
- ✅ Added N new agents
  - agent-name → Domain
- ✅ Updated agent inventory

### Files Modified
- path/to/file.md (N changes)

### Manual Review Needed
- item-name: Could not determine category

要更新的文档文件

主要目标（始终检查）：

• .claude/skills/CLAUDE.md - 技能目录
• .claude/skills/CLAUDE.md - 命令参考
• CLAUDE.md（根目录）- 仓库概览

次要目标（如果存在）：

• README.md - 项目 README
• docs/ 目录内容
• 任何包含技能／命令／Agent 数量的文件

分类规则

技能类别

模式	类别
ux-*、accessibility-*、design-*	用户体验与无障碍访问
git-*、github-*	版本控制与 GitHub
python-*、uv-*、ruff-*	Python 开发
typescript-*、nodejs-*、vitest-*	TypeScript/JavaScript
rust-*、cpp-*、embedded-*	系统编程语言
container-*、kubernetes-*、helm-*、terraform-*	基础设施与 DevOps
test-*、playwright-*、mutation-*	测试与质量
agent-*、multi-agent-*	元协调

技能命名空间

由技能目录名称的前缀决定：

• skills/git-*/SKILL.md → git: 命名空间
• skills/docs-*/SKILL.md → docs: 命名空间
• skills/*/SKILL.md（无前缀）→ 根级技能

错误处理

• 缺少文档文件：根据发现的内容使用模板创建
• YAML frontmatter 格式错误：发出警告并跳过该项，在摘要中报告
• 分类不明确：添加到“未分类”部分，并标记待审核
• 重复条目：发出警告并保留首次出现的条目

最佳实践

1. 添加功能后运行 - 让文档与实现保持同步
2. 先检查 dry-run - 应用更改前验证分类
3. 单独提交文档 - 使用 docs: conventional commit 前缀
4. 检查交叉引用 - 确保更新“另请参阅”部分

示例会话

# After adding new skills
/docs:sync --dry-run

# Review output, then apply
/docs:sync

# Commit the documentation updates
git add .claude/
git commit -m "docs: sync documentation with new UX implementation features"

另请参阅

• 命令：使用 /docs:generate 生成新文档
• 技能：使用 release-please-protection 实现自动版本管理
• 工作流：在 /project:new 或添加重大功能后运行