docs-sync

description	Sync docs with actual skills, commands, and agents. Use when docs are out of sync, updating the skill catalog, or regenerating command reference to fix mismatches.
args	[--scope <type>] [--dry-run] [--verbose]
argument-hint	--scope skills|commands|agents, --dry-run to preview, --verbose for details
allowed-tools	Bash, Grep, Glob, Read, Edit, Write, TodoWrite
created	"2025-12-16T00:00:00.000Z"
modified	"2026-05-09T00:00:00.000Z"
reviewed	"2026-04-25T00:00:00.000Z"
name	docs-sync

/docs:sync [OPTIONS]

When to Use This Skill

Use this skill when...	Use docs-generate instead when...
Skill / command / agent counts in README or CLAUDE.md drift from what the directories actually contain	Producing fresh API reference, README rewrites, or CHANGELOG content from code
New skills were added but not yet listed in the catalog tables	The catalog itself is fine and you need to author new documentation
Removed items still appear as stale entries in documentation	Drafting a service teardown checklist (use docs-decommission)
Cross-references and category groupings need reconciliation after a refactor	Converting an existing Markdown document to a print-ready PDF (use docs-latex)

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

3. 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

2. Categorize new items:

   For skills, determine category by:

   • 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

   For user-invocable skills, determine namespace from directory name:

   • skills/git-commit/SKILL.md → git: namespace
   • skills/handoffs/SKILL.md → Root level

   For agents, determine domain from description keywords

3. 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)

2. 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 |
   

3. Remove stale entries that no longer exist in codebase

4. 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

Pattern	Category
ux-*, accessibility-*, design-*	UX & Accessibility
git-*, github-*	Version Control & GitHub
python-*, uv-*, ruff-*	Python Development
typescript-*, nodejs-*, vitest-*	TypeScript/JavaScript
rust-*, cpp-*, embedded-*	Systems Languages
container-*, kubernetes-*, helm-*, terraform-*	Infrastructure & DevOps
test-*, playwright-*, mutation-*	Testing & Quality
agent-*, multi-agent-*	Meta & Coordination

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