The CLAUDE.md/README.md hierarchy is central to context hygiene. CLAUDE.md files are pure indexes -- tabular navigation with "What" and "When to read" columns that help LLMs (and humans) find relevant files without loading everything. README.md files capture invisible knowledge: architecture decisions, design tradeoffs, and invariants that are not apparent from reading code.

The doc-sync skill audits and synchronizes this hierarchy across a repository.

How It Works

The skill operates in five phases:

Discovery -- Maps all directories, identifies missing or outdated CLAUDE.md files
Audit -- Checks for drift (files added/removed but not indexed), misplaced content (architecture docs in CLAUDE.md instead of README.md)
Migration -- Moves architectural content from CLAUDE.md to README.md
Update -- Creates/updates indexes with proper tabular format
Verification -- Confirms complete coverage and correct structure

When to Use

Use this skill for:

Bootstrapping -- Adopting this workflow on an existing repository
After bulk changes -- Major refactors, directory restructuring
Periodic audits -- Checking for documentation drift
Onboarding -- Before starting work on an unfamiliar codebase

If you use the planning workflow consistently, the technical writer agent maintains documentation as part of execution. As such, doc-sync is primarily for bootstrapping or recovery -- not routine use.

Example Usage

Use your doc-sync skill to synchronize documentation across this repository

For targeted updates:

Use your doc-sync skill to update documentation in src/validators/