Docs Sync Checker

Instructions

Phase 1: SCAN

Goal: Discover all skills, agents, and commands in the repository filesystem. All discovery (file existence checks, YAML parsing, markdown extraction) must be deterministic -- no AI judgment on content quality.

Step 1: Run the scan script

python3 skills/docs-sync-checker/scripts/scan_tools.py --repo-root $HOME/claude-code-toolkit

Step 2: Validate discovery results

For each tool type, verify:

Skills (skills/*/SKILL.md):

• File has opening --- and closing --- YAML delimiters
• YAML contains name, description, and version fields
• name field matches directory name (e.g., skills/code-linting/ has name: code-linting)

Agents (agents/*.md):

• File has valid YAML frontmatter with name field
• Filename (without .md) matches YAML name value

Commands (commands/**/*.md):

• File exists as markdown in commands/ directory
• Namespaced commands in subdirectories (e.g., commands/code/cleanup.md) are detected

Step 3: Count and verify

## Scan Results
Skills found: [N]
Agents found: [N]
Commands found: [N]
YAML errors: [N] (must be 0 to proceed)

Gate: All tools discovered, all YAML valid, counts >0 for each type. Do NOT proceed until gate passes.

Phase 2: CROSS-REFERENCE

Goal: Extract documented tools from README files and compare with discovered tools. Each tool type has a primary documentation file: skills belong in skills/README.md, agents in agents/README.md, commands in commands/README.md.

Step 1: Run the documentation parser

python3 skills/docs-sync-checker/scripts/parse_docs.py --repo-root $HOME/claude-code-toolkit --scan-results /tmp/scan_results.json

Step 2: Parse each documentation file

These are the five documentation files to check -- no others:

Step 3: Build documented-tools registry

For each documentation file, collect the set of tool names found. This creates a mapping of {file -> [tool_names]} that Phase 3 will compare against the filesystem scan.

Step 4: Verify parse completeness

• All 5 documentation files found and parsed (warn if any missing)
• No parse errors on table/list structures
• Tool names extracted from each file

Gate: All documentation files parsed without errors. Do NOT proceed until gate passes.

Phase 3: DETECT

Goal: Compare discovered tools with documented tools to identify drift. This is a point-in-time snapshot -- it cannot tell you when drift occurred, only that it exists now.

Step 1: Compute set differences

For each tool type and its primary documentation file:

• missing = filesystem_tools - documented_tools (tools that exist but are not documented)
• stale = documented_tools - filesystem_tools (documented tools that no longer exist -- users waste time trying to invoke non-existent tools, so always flag these)

Step 2: Check version consistency

For tools that appear in both sets, compare:

• YAML version field vs. documented version (if version is documented)
• Flag mismatches where YAML is authoritative source of truth

Step 3: Categorize and assign severity

Severity reflects user impact: missing entries mean tools are undiscoverable, stale entries waste time, version mismatches cause confusion.

Step 4: Record issue details

For each issue, capture: tool type, tool name, tool path, affected documentation file(s), severity, and suggested fix action.

Gate: All issues categorized with severity. Do NOT proceed until gate passes.

Phase 4: REPORT

Goal: Generate human-readable report with actionable fix suggestions. Report facts concisely -- show data, not self-congratulatory descriptions. Target 100% sync score; even one missing entry erodes trust in all documentation.

Step 1: Run the report generator

python3 skills/docs-sync-checker/scripts/generate_report.py --issues /tmp/issues.json --output /tmp/sync-report.md

Step 2: Verify report structure

Report must include these sections:

1. Summary -- Total tools, issue counts by severity, sync score

   sync_score = (total_tools - total_issues) / total_tools * 100
   

2. HIGH Priority: Missing Entries -- For each missing tool, provide the exact markdown row/item to add to the appropriate README file

3. MEDIUM Priority: Stale Entries -- For each stale tool, identify the file and line to remove

4. LOW Priority: Version Mismatches -- For each mismatch, show YAML version (authoritative) vs. documented version

5. Files Checked -- List each documentation file with count of tools parsed from it

Step 3: Validate actionability

Every issue in the report must have a concrete suggested fix. No issue should say "review manually" without specifying what to review and where. The fix should enable a single-commit resolution -- tool files and documentation entries should be added/removed together.

Step 4: Report format for missing entries

For each missing skill, generate a suggested table row:

| skill-name | Description from YAML | `skill: skill-name` | - |

For each missing agent, generate a suggested table row:

| agent-name | Description from YAML |

For each missing command, generate a suggested list item:

- `/command-name` - Description from command file

Step 5: Cleanup

Remove any helper scripts and debug outputs created during execution.

Gate: Report generated with actionable suggestions for every issue.

Examples

Example 1: New Skill Missing from README

User created skills/my-new-skill/SKILL.md but forgot to update skills/README.md. Actions:

1. SCAN discovers my-new-skill in filesystem
2. CROSS-REFERENCE parses skills/README.md, does not find my-new-skill
3. DETECT flags as HIGH severity missing entry
4. REPORT suggests exact table row to add to skills/README.md

Example 2: Removed Agent Still Documented

User deleted agents/old-agent.md but agents/README.md still lists it. Actions:

1. SCAN does not find old-agent in filesystem
2. CROSS-REFERENCE finds old-agent in agents/README.md
3. DETECT flags as MEDIUM severity stale entry
4. REPORT suggests removing the row from agents/README.md

Example 3: Version Bump Without Doc Update

User updated version: 2.0.0 in skills/code-linting/SKILL.md but docs/REFERENCE.md still shows Version: 1.5.0. Actions:

1. SCAN reads YAML version as 2.0.0
2. CROSS-REFERENCE reads documented version as 1.5.0 from docs/REFERENCE.md
3. DETECT flags as LOW severity version mismatch
4. REPORT suggests updating version line in docs/REFERENCE.md to 2.0.0

Example 4: Batch Changes After Refactor

User created 3 new skills and deleted 2 old ones in a refactoring PR. Actions:

1. SCAN discovers 3 new skills in filesystem, does not find 2 removed skills
2. CROSS-REFERENCE finds 2 stale entries and 3 absent entries in skills/README.md
3. DETECT flags 3 HIGH (missing) + 2 MEDIUM (stale) issues
4. REPORT provides exact table rows to add and identifies rows to remove

Error Handling

Error: "YAML Parse Error"

Cause: Invalid frontmatter -- missing --- delimiters, tabs instead of spaces, or missing required fields Solution:

1. Check file has opening --- on line 1 and closing --- after YAML block
2. Verify no tab characters in YAML (spaces only)
3. Confirm required fields present: name, description, version
4. Validate manually: head -20 {file_path} and check syntax

Error: "Documentation File Not Found"

Cause: Expected README file does not exist at expected path Solution:

1. Verify --repo-root path is correct
2. Check that skills/README.md, agents/README.md, commands/README.md exist
3. If file is legitimately missing, create a placeholder with the expected table/list header
4. Re-run scan after creating placeholder

Error: "No Tools Discovered"

Cause: Wrong --repo-root path, empty directories, or no SKILL.md files Solution:

1. Verify the repo root path points to the correct repository
2. Confirm skills/, agents/, commands/ directories exist and are not empty
3. Check that skill directories contain SKILL.md (not just other files)
4. Run with --debug flag for verbose discovery output

Error: "Markdown Parse Error"

Cause: Table missing separator row, mismatched column counts, or malformed list items Solution:

1. Check table has header row, separator row (|---|---|), and data rows
2. Verify all rows have the same number of pipe-delimited columns
3. For lists, verify consistent format: - /command - Description
4. See references/markdown-formats.md for complete format specifications

References

• ${CLAUDE_SKILL_DIR}/references/documentation-structure.md: Documentation file matrix, required fields per location, cross-reference requirements
• ${CLAUDE_SKILL_DIR}/references/markdown-formats.md: Expected table/list formats for each README file, parsing rules, common formatting errors
• ${CLAUDE_SKILL_DIR}/references/sync-rules.md: Synchronization rules, severity levels, deprecation handling, namespace rules
• ${CLAUDE_SKILL_DIR}/references/examples.md: Before/after examples for adding, removing, updating, and batch documentation changes
• ${CLAUDE_SKILL_DIR}/references/integration-guide.md: CI/CD setup, pre-commit hooks, auto-fix mode, JSON output, workflow integration