docs-sync
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.
How do I install this agent skill?
npx skills add https://github.com/laurigates/claude-plugins --skill docs-syncIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill synchronizes codebase documentation by scanning for skills and agents. It is mostly safe, but its mechanism for ingesting metadata from external files creates a potential surface for indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
/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, orall(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
-
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 -
Extract metadata from each item:
- Skills: Parse YAML frontmatter for
nameanddescription - Commands: Parse
descriptionfrom frontmatter, infer namespace from path - Agents: Parse frontmatter for
name,description,tools
- Skills: Parse YAML frontmatter for
-
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
-
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
-
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:namespaceskills/handoffs/SKILL.md→ Root level
For agents, determine domain from description keywords
- Name patterns:
-
Identify documentation sections to update:
- Count patterns:
**N skills**,N total,(N skills) - List sections by category/namespace
- Summary tables
- Count patterns:
Step 3: Apply updates
-
Update counts throughout documentation:
- Search for patterns like
**63 skills**or63 specialized skills - Replace with accurate count
- Update category counts like
### Core Development (9 skills)
- Search for patterns like
-
Add new items to appropriate sections:
Skills catalog format:
### Category Name (N skills) - **skill-name** - Description from SKILL.md frontmatterCommand table format:
| Namespace | Commands | Purpose | | `/command` | Description | Usage context |Agent inventory format:
| Agent | Purpose | Key Tools | | **agent-name** | Description | Tool1, Tool2 | -
Remove stale entries that no longer exist in codebase
-
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 referenceCLAUDE.md(root) - Repository overview
Secondary targets (if they exist):
README.md- Project READMEdocs/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:namespaceskills/docs-*/SKILL.md→docs:namespaceskills/*/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
- Run after adding features - Keep docs in sync with implementation
- Review dry-run first - Verify categorization before applying
- Commit docs separately - Use
docs:conventional commit prefix - 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:generatefor generating new documentation - Skills:
release-please-protectionfor automated versioning - Workflow: Run after
/project:newor major feature additions
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laurigates/claude-plugins/docs-sync">View docs-sync on skillZs</a>