doc-sync_skill

Overview

This skill synchronizes repository documentation by maintaining CLAUDE.md navigation indexes and migrating invisible knowledge into README.md files where appropriate. It performs discovery, audits, content migration, index updates, and verification to ensure consistent, actionable docs across a given scope. Use it to keep navigation indexes accurate and to separate operational instructions from design rationale.

How this skill works

The skill first resolves scope (repository-wide, directory, or file parent) and discovers directories to inspect. It audits each directory for CLAUDE.md presence, table-based index accuracy, missing or stale entries, and misplaced prose. When explanatory content is found in CLAUDE.md, the tool migrates that material into README.md, replaces CLAUDE.md with a pure index, and updates tables to include README.md. A final verification pass confirms coverage, format consistency, and that no drift remains.

When to use it

• You want repository-wide alignment of CLAUDE.md navigation indexes.
• A directory’s CLAUDE.md contains architecture or design prose that should be moved to README.md.
• Files and subdirectories are missing from CLAUDE.md indexes or indexes contain stale entries.
• You need a repeatable process to enforce documentation conventions across many directories.
• You want to generate a report summarizing created/updated docs and verification results.

Best practices

• Always determine scope before making changes: REPOSITORY-WIDE vs DIRECTORY vs FILE parent.
• Treat CLAUDE.md as an operational index only; move all rationale/architecture to README.md.
• Apply the "Is this WHY or HOW?" test: WHY -> README.md, HOW -> CLAUDE.md (commands/procedures).
• Skip generating CLAUDE.md for excluded directories (generated builds, vendored deps, stub dirs).
• Include README.md entries in CLAUDE.md tables and keep table descriptions action-oriented (When to read triggers).

Example use cases

• Run a full repo audit to create CLAUDE.md for every non-excluded directory and produce a Doc Sync Report.
• Fix a directory where CLAUDE.md mixes architecture prose with commands by migrating prose to README.md and normalizing the index.
• Update a single component’s parent directory CLAUDE.md after adding new source files so indexes and triggers reflect current contents.
• Enforce documentation conventions in CI by running the skill as part of a pre-merge check and flagging drift.
• Generate a changes summary listing created/updated CLAUDE.md and README.md files for a release or handoff.