# Sync Claude > Synchronize and validate Claude documentation (CLAUDE.md files and skills) before commits. Ensures documentation accuracy by validating all claims against actual codebase state. Use when: (1) Before creating a PR to ensure docs are accurate, (2) After making changes that might invalidate documentation claims, (3) When explicitly syncing Claude docs, (4) When reviewing documentation for staleness. Triggers: "sync claude", "validate claude docs", "check documentation", "update CLAUDE.md", "before commit", "docs out of sync", "/sync-claude", "stale documentation" Two modes: - full: Exhaustive validation of all Claude docs in repository - changed: Smart detection of docs affected by current branch changes - Skill: `majiayu000/sync-claude` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add majiayu000/sync-claude` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/sync-claude/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/sync-claude --- # Claude Documentation Sync Validate and synchronize all Claude-related documentation before commits. ## Quick Start ``` Mode selection: - full → Exhaustive validation of all docs - changed → Only docs affected by current branch (default) ``` ## Execution Flow ### Phase 1: Discovery **Full mode**: Find all Claude docs in repository: - `**/CLAUDE.md` (excluding `.terragrunt-cache/`, `.terragrunt-stack/`) - `.claude/skills/*/SKILL.md` - `.claude/skills/*/references/*.md` **Changed mode**: Analyze branch diff: 1. Get changed files: `git diff --name-only origin/main...HEAD` 2. Find directly modified Claude docs 3. Find docs that reference changed paths (smart detection) ### Phase 2: Parallel Validation (Haiku Agents) Spawn parallel Haiku agents organized by validation type: #### Agent Group A: Path Validators (by directory) One agent per major directory validates file/directory references: - `infrastructure/` paths - `kubernetes/` paths - `.taskfiles/` paths - Root and other paths **Validation checks:** - File paths mentioned exist: `[path/to/file](path/to/file)` - Directory paths exist: `infrastructure/modules/` - Glob patterns return results: `**/*.tf` #### Agent Group B: Code Reference Validators Validate code-level claims: - Function/class names exist where documented - Line number references are approximately accurate (±10 lines) - Variable names in examples exist in referenced files #### Agent Group C: Command Validators Validate command examples: - `task ` commands exist in Taskfile - CLI tools referenced are in Brewfile - Command syntax is valid (dry-run where safe) #### Agent Group D: Cross-Reference Validators Validate documentation consistency: - Skill references in CLAUDE.md match actual skills - Table entries match actual directories - Runbook references exist ### Phase 3: Aggregation Collect results from all agents into a unified report: ``` ┌─────────────────────────────────────────────────────────────┐ │ SYNC-CLAUDE VALIDATION REPORT │ ├─────────────────────────────────────────────────────────────┤ │ Mode: [full|changed] │ │ Docs Scanned: N │ │ Issues Found: N │ ├─────────────────────────────────────────────────────────────┤ │ ISSUES BY CATEGORY: │ │ │ │ 🔴 Path References (N issues) │ │ • infrastructure/CLAUDE.md:45 - path not found │ │ Referenced: infrastructure/units/foo/ │ │ Suggestion: Path was renamed to infrastructure/units/bar│ │ │ │ 🟡 Command References (N issues) │ │ • .taskfiles/CLAUDE.md:67 - task not found │ │ Referenced: task tg:deploy-live │ │ Suggestion: Task was renamed to task tg:apply-live │ │ │ │ 🟢 Valid References: N │ └─────────────────────────────────────────────────────────────┘ ``` ### Phase 4: Opus Validation Spawn Opus agent to: 1. Review aggregated findings 2. Prioritize by impact (breaking vs cosmetic) 3. Generate proposed edits for each issue 4. Present final change list for approval ## Agent Prompts ### Discovery Agent (Haiku) ``` Discover all Claude documentation files in the repository. Search patterns: - **/CLAUDE.md (exclude .terragrunt-cache/, .terragrunt-stack/) - .claude/skills/*/SKILL.md - .claude/skills/*/references/*.md For each file found, extract: 1. All file path references (markdown links, code blocks) 2. All directory references 3. All command examples (task, kubectl, git, etc.) 4. All cross-references to other docs/skills Return structured JSON: { "file": "path/to/doc.md", "path_refs": ["path1", "path2"], "dir_refs": ["dir1/", "dir2/"], "commands": ["task foo", "kubectl get"], "cross_refs": ["skill:name", "doc:path"] } ``` ### Path Validator Agent (Haiku) ``` Validate file and directory references in Claude documentation. Input: List of {doc_path, references} For each reference: 1. Check if path exists using Glob/Read 2. If not found, search for similar paths (fuzzy match) 3. Determine if path was renamed, moved, or deleted Return: { "valid": [...], "invalid": [ { "doc": "path/to/doc.md", "line": 45, "reference": "infrastructure/foo/", "status": "not_found", "suggestion": "Renamed to infrastructure/bar/" } ] } ``` ### Command Validator Agent (Haiku) ``` Validate command examples in Claude documentation. Input: List of {doc_path, commands} Validation steps: 1. task commands: Verify in Taskfile.yaml or .taskfiles/* 2. CLI tools: Verify in Brewfile 3. kubectl commands: Syntax check only (no cluster access) 4. git commands: Syntax validation Return: { "valid": [...], "invalid": [ { "doc": "path/to/doc.md", "line": 67, "command": "task tg:deploy", "status": "task_not_found", "suggestion": "Did you mean: task tg:apply-*" } ] } ``` ### Change Impact Analyzer (Haiku) - Changed Mode Only ``` Analyze git diff to find impacted documentation. Steps: 1. Parse diff: git diff --name-only origin/main...HEAD 2. For each changed file, find docs that might reference it: - Direct path references - Parent directory references - Related command references (if Taskfile changed) 3. Include any directly modified Claude docs Return list of doc paths requiring validation. ``` ### Opus Validator Agent ``` Review sync-claude validation results and propose fixes. Input: Aggregated validation results from all Haiku agents Tasks: 1. Deduplicate findings 2. Categorize by severity: - CRITICAL: Broken references users will hit - WARNING: Outdated but still functional - INFO: Style/cosmetic issues 3. For each issue, generate a proposed Edit: - old_string: exact text to replace - new_string: corrected text 4. Verify proposed edits don't break other references Output format: { "summary": { "total_issues": N, "critical": N, "warning": N, "info": N }, "proposed_edits": [ { "file": "path/to/doc.md", "severity": "CRITICAL", "description": "Fix broken path reference", "old_string": "[foo](infrastructure/foo/)", "new_string": "[foo](infrastructure/bar/)" } ] } Present edits for user approval before applying. ``` ## Mode Selection Logic ``` IF user specifies mode: USE specified mode ELSE IF on main branch: USE full mode ELSE IF branch has commits ahead of origin/main: USE changed mode ELSE: USE full mode (no changes to analyze) ``` ## Exclusions Always exclude from scanning: - `.terragrunt-cache/` - `.terragrunt-stack/` - `node_modules/` - `.git/` - `*.rendered/` ## Error Handling If an agent fails: 1. Log the failure with context 2. Continue with other agents 3. Mark affected validations as "INCOMPLETE" 4. Include in final report for manual review