docs-sync（文档同步）

/docs:sync [OPTIONS]

Scan the codebase for skills, commands, and agents, then update all documentation to reflect the current state. Fixes count mismatches, adds missing entries, and removes stale references.

Usage

/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

Parameters

• --scope <type> - Limit sync to specific type: skills, commands, agents, or all (default)
• --dry-run - Preview changes without modifying files
• --verbose - Show detailed progress during scanning

Execution

Execute this documentation sync workflow:

Step 1: Discover codebase items

1. Scan source directories: # 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. Extract metadata from each item:

- Skills: Parse YAML frontmatter for name and description - Commands: Parse description from frontmatter, infer namespace from path - Agents: Parse frontmatter for name, description, tools

1. Parse existing documentation:

- .claude/skills/CLAUDE.md - Current skill catalog with categories - .claude/skills/CLAUDE.md - Command reference with namespaces - Root CLAUDE.md - Summary counts and highlights

Step 2: Analyze differences

1. Compare actual vs documented:

- Find items in directories but not in documentation (NEW) - Find items in documentation but not in directories (STALE) - Check if counts match

1. Categorize new items: For skills, determine category by: For user-invocable skills, determine namespace from directory name: For agents, determine domain from description keywords

- Name patterns: ux-*, git-*, python-* → matching category - Description keywords: "accessibility", "testing", "infrastructure" - Similar existing skills in same domain - If uncertain, suggest "Uncategorized" for manual review - skills/git-commit/SKILL.md → git: namespace - skills/handoffs/SKILL.md → Root level

1. Identify documentation sections to update:

- Count patterns: **N skills**, N total, (N skills) - List sections by category/namespace - Summary tables

Step 3: Apply updates

1. Update counts throughout documentation:

- Search for patterns like **63 skills** or 63 specialized skills - Replace with accurate count - Update category counts like ### Core Development (9 skills)

1. Add new items to appropriate sections: Skills catalog format: ### Category Name (N skills) - **skill-name** - Description from SKILL.md frontmatter Command table format: ` | Namespace | Commands | Purpose | | /command | Description | Usage context | **Agent inventory format**: | Agent | Purpose | Key Tools | | agent-name | Description | Tool1, Tool2 |`
2. Remove stale entries that no longer exist in codebase
3. Update cross-references:

- "See also" sections - Related skills/commands lists

Step 4: Report results

Generate summary of changes:

## 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

Documentation Files to Update

Primary targets (always check):

• .claude/skills/CLAUDE.md - Skills catalog
• .claude/skills/CLAUDE.md - Commands reference
• CLAUDE.md (root) - Repository overview

Secondary targets (if they exist):

• README.md - Project README
• docs/ directory content
• Any file containing skill/command/agent counts

Categorization Rules

Skill Categories

Skill Namespaces

Determined by skill directory name prefix:

• skills/git-*/SKILL.md → git: namespace
• skills/docs-*/SKILL.md → docs: namespace
• skills/*/SKILL.md (no prefix) → Root level skills

Error Handling

• Missing documentation file: Create from template with discovered content
• Malformed YAML frontmatter: Warn and skip item, report in summary
• Ambiguous categorization: Add to "Uncategorized" section, flag for review
• Duplicate entries: Warn and keep first occurrence

Best Practices

1. Run after adding features - Keep docs in sync with implementation
2. Review dry-run first - Verify categorization before applying
3. Commit docs separately - Use docs: conventional commit prefix
4. Check cross-references - Ensure "See also" sections are updated

Example Session

# 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"

See Also

• Commands: /docs:generate for generating new documentation
• Skills: release-please-protection for automated versioning
• Workflow: Run after /project:new or major feature additions