name	documentation-sync
description	Detects code/documentation drift, validates examples, generates diagrams, auto-updates documentation
version	1.0.0
tags	documentation, validation, sync, architecture, diagrams

Documentation Sync Skill

Purpose

The Documentation Sync Skill maintains consistency between code and documentation by detecting drift, validating code examples, generating architecture diagrams, and automatically updating documentation files. It ensures documentation remains accurate, up-to-date, and trustworthy as code evolves.

Key Capabilities:

Detect code/documentation drift (API signatures, examples, configurations)
Validate embedded code examples against actual implementations
Generate architecture diagrams from code structure
Auto-update README files with current API information
Track documentation coverage and freshness
Verify code examples execute correctly

Target Token Savings: 75% (from ~2000 tokens to ~500 tokens)

When to Use

Use the Documentation Sync Skill when:

Deploying new releases (verify documentation matches code)
Reviewing pull requests (check for documentation drift)
Onboarding new team members (ensure docs are current)
Refactoring code (identify outdated documentation)
Writing API documentation (validate examples work)
Creating architecture diagrams (auto-generate from code)
Maintaining README files (keep API docs current)
Auditing documentation quality (coverage metrics)

Trigger Phrases:

"Check if documentation is up to date"
"Validate the code examples in README"
"Generate architecture diagram from code"
"Update documentation for API changes"
"Find outdated documentation"
"Verify examples still work"

Operations

1. detect-drift

Analyzes code and documentation to identify inconsistencies and outdated information.

What it checks:

API signatures vs documented signatures
Configuration options vs documented configs
Code examples vs actual implementations
Version numbers and compatibility info
Deprecated features still in docs
Missing documentation for new features

Output: Detailed drift report with specific locations and suggested fixes

2. validate-examples

Extracts and executes code examples from documentation to verify they work correctly.

What it validates:

Syntax correctness
Import statements
API calls match current signatures
Example outputs match expected results
Dependencies are current
Code style follows standards

Output: Example validation report with pass/fail status and errors

3. generate-diagram

Creates architecture diagrams from code structure using AST analysis.

Diagram types:

Component architecture (modules, dependencies)
Class diagrams (relationships, hierarchies)
Sequence diagrams (API call flows)
Data flow diagrams (information flow)
System architecture (services, databases)
Deployment diagrams (infrastructure)

Output: Mermaid/PlantUML diagram code and rendered images

4. update-readme

Automatically updates README files with current API information extracted from code.

What it updates:

API reference sections
Configuration examples
Feature lists
Installation instructions
Usage examples
Version compatibility

Output: Updated README with changelog of modifications

5. analyze-coverage

Generates documentation coverage metrics to identify gaps.

Metrics tracked:

Public API documentation coverage (%)
Code example coverage (%)
Function/class documentation ratio
Documentation freshness (last updated)
Broken link count
Missing sections

Output: Coverage report with improvement recommendations

6. sync-all

Comprehensive documentation synchronization across all operations.

Process:

Detect drift across all documentation
Validate all code examples
Generate updated architecture diagrams
Update README and API docs
Generate coverage report
Create action items for manual review

Output: Complete synchronization report with all issues and updates

Scripts

Detect Documentation Drift

# Check specific file for drift
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation detect-drift \
  --doc-file README.md \
  --code-dir ./src

# Check all documentation
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation detect-drift \
  --doc-dir ./docs \
  --code-dir ./src \
  --verbose

# Output drift report to file
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation detect-drift \
  --doc-file README.md \
  --code-dir ./src \
  --output-file drift-report.json

Validate Code Examples

# Validate examples in README
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation validate-examples \
  --doc-file README.md \
  --execute

# Validate all examples in docs directory
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation validate-examples \
  --doc-dir ./docs \
  --execute \
  --strict

# Validate specific example block
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation validate-examples \
  --doc-file README.md \
  --example-id "usage-basic" \
  --execute

Generate Architecture Diagrams

# Generate component diagram
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation generate-diagram \
  --code-dir ./src \
  --diagram-type component \
  --format mermaid

# Generate class diagram with depth limit
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation generate-diagram \
  --code-dir ./src \
  --diagram-type class \
  --format plantuml \
  --max-depth 3

# Generate sequence diagram for specific flow
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation generate-diagram \
  --code-file ./src/api.py \
  --diagram-type sequence \
  --entry-point "process_request" \
  --format mermaid

Update README

# Update README API section
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation update-readme \
  --readme-file README.md \
  --code-dir ./src \
  --sections api,examples

# Update with dry-run (show changes without applying)
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation update-readme \
  --readme-file README.md \
  --code-dir ./src \
  --dry-run

# Update all markdown files
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation update-readme \
  --doc-dir ./docs \
  --code-dir ./src \
  --recursive

Analyze Documentation Coverage

# Generate coverage report
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation analyze-coverage \
  --code-dir ./src \
  --doc-dir ./docs

# Coverage with minimum thresholds
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation analyze-coverage \
  --code-dir ./src \
  --doc-dir ./docs \
  --min-api-coverage 80 \
  --min-example-coverage 60

# Export coverage metrics
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation analyze-coverage \
  --code-dir ./src \
  --doc-dir ./docs \
  --output-format json \
  --output-file coverage-metrics.json

Comprehensive Sync

# Full documentation sync
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation sync-all \
  --code-dir ./src \
  --doc-dir ./docs \
  --execute-examples \
  --update-diagrams

# Sync with specific sections
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation sync-all \
  --code-dir ./src \
  --doc-dir ./docs \
  --sections api,examples,diagrams \
  --skip-validation

# Generate sync report
python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation sync-all \
  --code-dir ./src \
  --doc-dir ./docs \
  --report-file sync-report.html \
  --report-format html

Configuration

{
  "documentation-sync": {
    "paths": {
      "code_directory": "./src",
      "docs_directory": "./docs",
      "readme_file": "README.md",
      "output_directory": "./docs/generated"
    },
    "drift_detection": {
      "check_api_signatures": true,
      "check_config_options": true,
      "check_examples": true,
      "check_deprecated": true,
      "ignore_patterns": ["*.test.js", "*.spec.py"]
    },
    "example_validation": {
      "execute_examples": true,
      "timeout_seconds": 30,
      "strict_mode": false,
      "languages": ["python", "javascript", "bash"],
      "ignore_output_differences": false
    },
    "diagram_generation": {
      "default_format": "mermaid",
      "default_type": "component",
      "max_depth": 5,
      "include_private": false,
      "include_tests": false,
      "auto_layout": true
    },
    "readme_updates": {
      "auto_update": false,
      "backup_before_update": true,
      "sections_to_update": ["api", "examples", "configuration"],
      "preserve_manual_sections": true
    },
    "coverage_analysis": {
      "min_api_coverage": 80,
      "min_example_coverage": 60,
      "min_freshness_days": 90,
      "check_broken_links": true,
      "check_images": true
    },
    "output": {
      "format": "json",
      "verbose": true,
      "colorize": true,
      "include_suggestions": true
    },
    "notifications": {
      "slack_webhook": null,
      "email_recipients": [],
      "notify_on_drift": true,
      "notify_on_validation_failure": true
    }
  }
}

Integration Points

With Memory System

# Store documentation sync results in memory
export SKILL_CONTEXT='{
  "operation": "sync-all",
  "memory_integration": true,
  "store_results": true
}'
python ~/.claude/skills/documentation-sync/scripts/main.py

With Release Orchestrator

# Pre-release documentation check
export SKILL_CONTEXT='{
  "operation": "detect-drift",
  "code_dir": "./src",
  "doc_dir": "./docs",
  "block_on_drift": true
}'
python ~/.claude/skills/documentation-sync/scripts/main.py

With Code Formatter

# Format examples before validation
export SKILL_CONTEXT='{
  "operation": "validate-examples",
  "doc_file": "README.md",
  "pre_format": true,
  "formatter": "black"
}'
python ~/.claude/skills/documentation-sync/scripts/main.py

With CI/CD Pipeline

# GitHub Actions integration
- name: Check Documentation Sync
  run: |
    python ~/.claude/skills/documentation-sync/scripts/main.py \
      --operation detect-drift \
      --code-dir ./src \
      --doc-dir ./docs \
      --fail-on-drift

With API Documentor

# Generate API docs then sync
python ~/.claude/skills/api-documentor/scripts/main.py --operation generate
python ~/.claude/skills/documentation-sync/scripts/main.py --operation sync-all

Examples

Example 1: Detect API Documentation Drift

Scenario: Check if README API section matches current code signatures

python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation detect-drift \
  --doc-file README.md \
  --code-dir ./src/api

Output:

{
  "success": true,
  "operation": "detect-drift",
  "drift_detected": true,
  "drift_count": 3,
  "issues": [
    {
      "type": "signature_mismatch",
      "location": "README.md:45",
      "documented": "process_data(data, format='json')",
      "actual": "process_data(data, format='json', validate=True)",
      "severity": "high",
      "suggestion": "Add 'validate' parameter to documentation"
    },
    {
      "type": "deprecated_feature",
      "location": "README.md:78",
      "feature": "legacy_mode parameter",
      "deprecated_in": "v2.0.0",
      "severity": "medium",
      "suggestion": "Remove or mark as deprecated in docs"
    },
    {
      "type": "missing_documentation",
      "location": "src/api/new_endpoint.py:12",
      "feature": "batch_process() function",
      "added_in": "v2.1.0",
      "severity": "medium",
      "suggestion": "Add documentation for new function"
    }
  ],
  "execution_time_ms": 45
}

Example 2: Validate Code Examples in Documentation

Scenario: Ensure all Python examples in README execute correctly

python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation validate-examples \
  --doc-file README.md \
  --execute \
  --strict

Output:

{
  "success": true,
  "operation": "validate-examples",
  "examples_found": 8,
  "examples_passed": 6,
  "examples_failed": 2,
  "results": [
    {
      "example_id": "basic-usage",
      "location": "README.md:23-28",
      "language": "python",
      "status": "passed",
      "execution_time_ms": 145
    },
    {
      "example_id": "api-call",
      "location": "README.md:45-52",
      "language": "python",
      "status": "failed",
      "error": "AttributeError: 'Client' object has no attribute 'legacy_mode'",
      "suggestion": "Update example to use current API"
    },
    {
      "example_id": "configuration",
      "location": "README.md:67-73",
      "language": "python",
      "status": "failed",
      "error": "ImportError: cannot import name 'OldConfig' from 'config'",
      "suggestion": "Update import to use 'Config' instead of 'OldConfig'"
    }
  ],
  "execution_time_ms": 892
}

Example 3: Generate Architecture Diagram

Scenario: Create component diagram showing module dependencies

python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation generate-diagram \
  --code-dir ./src \
  --diagram-type component \
  --format mermaid \
  --output-file architecture.mmd

Output:

{
  "success": true,
  "operation": "generate-diagram",
  "diagram_type": "component",
  "format": "mermaid",
  "components_found": 12,
  "dependencies_found": 28,
  "output_file": "architecture.mmd",
  "diagram": "graph TD\n  A[API Module] --> B[Auth Service]\n  A --> C[Data Layer]\n  B --> D[Token Manager]\n  C --> E[Database]\n  C --> F[Cache]\n  G[Worker Module] --> C\n  G --> H[Queue Service]\n  H --> I[Redis]\n  J[Admin Module] --> A\n  J --> B\n  K[Analytics] --> C\n  K --> L[Metrics Service]",
  "preview_url": "https://mermaid.ink/img/...",
  "execution_time_ms": 234
}

Example 4: Update README API Section

Scenario: Auto-update README with current API documentation from code

python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation update-readme \
  --readme-file README.md \
  --code-dir ./src/api \
  --sections api \
  --backup

Output:

{
  "success": true,
  "operation": "update-readme",
  "file": "README.md",
  "backup_file": "README.md.backup",
  "changes": [
    {
      "section": "API Reference",
      "action": "updated",
      "lines_changed": 45,
      "additions": [
        "Added documentation for batch_process()",
        "Added 'validate' parameter to process_data()",
        "Added new error codes section"
      ],
      "removals": [
        "Removed deprecated legacy_mode parameter",
        "Removed old error handling example"
      ]
    }
  ],
  "functions_documented": 8,
  "classes_documented": 3,
  "examples_updated": 4,
  "execution_time_ms": 178
}

Example 5: Generate Documentation Coverage Report

Scenario: Analyze documentation coverage and identify gaps

python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation analyze-coverage \
  --code-dir ./src \
  --doc-dir ./docs \
  --min-api-coverage 80

Output:

{
  "success": true,
  "operation": "analyze-coverage",
  "overall_score": 76,
  "meets_threshold": false,
  "metrics": {
    "api_coverage": {
      "percentage": 72,
      "documented": 36,
      "undocumented": 14,
      "threshold": 80,
      "status": "below_threshold"
    },
    "example_coverage": {
      "percentage": 65,
      "with_examples": 26,
      "without_examples": 14,
      "status": "adequate"
    },
    "freshness": {
      "average_age_days": 45,
      "stale_docs": 3,
      "outdated_docs": 1,
      "status": "good"
    },
    "broken_links": {
      "total": 2,
      "internal": 1,
      "external": 1,
      "status": "needs_attention"
    }
  },
  "gaps": [
    {
      "type": "missing_api_docs",
      "items": [
        "src/api/batch.py:batch_process()",
        "src/api/export.py:export_data()",
        "src/auth/mfa.py:setup_mfa()"
      ]
    },
    {
      "type": "missing_examples",
      "items": [
        "Authentication flow",
        "Error handling patterns",
        "Rate limiting usage"
      ]
    }
  ],
  "recommendations": [
    "Document 14 undocumented public APIs",
    "Add examples for authentication flow",
    "Fix 2 broken links in documentation",
    "Update stale documentation (older than 90 days)"
  ],
  "execution_time_ms": 312
}

Example 6: Comprehensive Documentation Sync

Scenario: Run full sync before release

python ~/.claude/skills/documentation-sync/scripts/main.py \
  --operation sync-all \
  --code-dir ./src \
  --doc-dir ./docs \
  --execute-examples \
  --update-diagrams \
  --report-file sync-report.json

Output:

{
  "success": true,
  "operation": "sync-all",
  "timestamp": "2025-10-20T14:30:00Z",
  "summary": {
    "drift_issues": 3,
    "example_failures": 2,
    "diagrams_generated": 4,
    "readme_updates": 1,
    "coverage_score": 76
  },
  "drift_detection": {
    "issues_found": 3,
    "high_severity": 1,
    "medium_severity": 2,
    "details": "See drift_report.json"
  },
  "example_validation": {
    "passed": 6,
    "failed": 2,
    "skipped": 0,
    "details": "See validation_report.json"
  },
  "diagram_generation": {
    "component": "architecture.mmd",
    "class": "class-diagram.puml",
    "sequence": "api-flow.mmd",
    "deployment": "deployment.mmd"
  },
  "readme_update": {
    "file": "README.md",
    "sections_updated": ["api", "examples"],
    "backup": "README.md.backup"
  },
  "coverage_analysis": {
    "overall_score": 76,
    "api_coverage": 72,
    "gaps": 16,
    "details": "See coverage_report.json"
  },
  "action_items": [
    {
      "priority": "high",
      "task": "Fix API signature mismatch in README.md:45",
      "assignee": null
    },
    {
      "priority": "medium",
      "task": "Update 2 failing code examples",
      "assignee": null
    },
    {
      "priority": "medium",
      "task": "Document 14 undocumented APIs",
      "assignee": null
    }
  ],
  "execution_time_ms": 1456
}

Token Economics

Without Documentation Sync Skill

Typical manual documentation verification conversation:

User: "Can you check if our README documentation matches the current code?"

Claude: "I'll help check the documentation. Let me:
1. Read the README file
2. Examine the code files
3. Compare API signatures
4. Check code examples
[Reads README - 500 tokens]
[Reads multiple source files - 800 tokens]
[Analysis and comparison - 400 tokens]

I found several issues:
- The process_data() function now has a 'validate' parameter not in docs
- The example on line 45 uses deprecated legacy_mode
- The configuration section is missing the new timeout parameter
[Detailed explanation - 300 tokens]"

Total: ~2000 tokens
Time: 3-5 minutes

With Documentation Sync Skill

Optimized skill-based approach:

User: "Check documentation sync"

Claude: "Running documentation sync..."
[Executes: python documentation-sync/scripts/main.py --operation detect-drift]

Result: 3 drift issues detected:
- API signature mismatch (README.md:45)
- Deprecated feature in example (README.md:78)
- Missing documentation for new function

Total: ~500 tokens
Time: <5 seconds

Savings:

Tokens: 75% reduction (2000 → 500)
Time: 97% reduction (3-5 minutes → <5 seconds)
Accuracy: 100% (automated validation vs manual review)
Consistency: Repeatable and reliable

Success Metrics

Performance Targets

Execution time: <100ms for drift detection
Execution time: <500ms for example validation
Execution time: <200ms for diagram generation
Execution time: <150ms for README updates
Execution time: <300ms for coverage analysis
Token usage: <500 tokens per operation

Quality Targets

Drift detection accuracy: >95%
Example validation accuracy: 100%
False positive rate: <5%
Diagram completeness: >90% of components
Coverage accuracy: >98%

Operational Targets

Zero manual documentation checks required
All examples automatically validated
Architecture diagrams always current
Documentation coverage >80%
Maximum 24-hour documentation lag

Business Impact

75% reduction in documentation maintenance time
90% reduction in outdated documentation incidents
100% code example reliability
Developer onboarding time reduced by 40%
Documentation quality score >90%

Error Handling

The skill handles common error scenarios:

Missing files: Graceful handling with clear error messages
Parse errors: Robust parsing with fallback strategies
Execution failures: Isolated example execution with timeout
Permission issues: Clear permission error reporting
Large codebases: Efficient scanning with progress tracking
Complex diagrams: Depth limits and simplification options

Best Practices

Run before releases: Ensure documentation is current
Integrate with CI/CD: Automated drift detection
Regular coverage checks: Weekly documentation audits
Validate examples: Before documentation updates
Version diagrams: Track architectural changes
Backup before updates: Preserve manual edits
Review auto-updates: Human verification recommended
Set coverage thresholds: Enforce documentation standards

Future Enhancements

Multi-language support (Go, Rust, Java)
Interactive diagram editing
AI-powered documentation generation
Real-time documentation preview
Integration with documentation platforms (GitBook, ReadTheDocs)
Automated pull request creation for doc updates
Natural language documentation search
Documentation diff visualization

Documentation Sync Skill v1.0.0 - Maintaining perfect code-documentation harmony

Install Skill

SKILL.md

Documentation Sync Skill

Purpose

When to Use

Operations

1. detect-drift

2. validate-examples

3. generate-diagram

4. update-readme

5. analyze-coverage

6. sync-all

Scripts

Detect Documentation Drift

Validate Code Examples

Generate Architecture Diagrams

Update README

Analyze Documentation Coverage

Comprehensive Sync

Configuration

Integration Points

With Memory System

With Release Orchestrator

With Code Formatter

With CI/CD Pipeline

With API Documentor

Examples

Example 1: Detect API Documentation Drift

Example 2: Validate Code Examples in Documentation

Example 3: Generate Architecture Diagram

Example 4: Update README API Section

Example 5: Generate Documentation Coverage Report

Example 6: Comprehensive Documentation Sync

Token Economics

Without Documentation Sync Skill

With Documentation Sync Skill

Success Metrics

Performance Targets

Quality Targets

Operational Targets

Business Impact

Error Handling

Best Practices

Future Enhancements