doc-sync

The doc-sync skill is an automated documentation management tool designed to enforce context hygiene in AI-assisted development environments. It maintains a two-file standard: CLAUDE.md for operational navigation and README.md for architectural invisible knowledge. By scanning the repository, it maps directory structures, audits drift, and migrates misplaced architectural prose from navigation files into structured documentation. This ensures that AI agents are not overwhelmed by large context windows, receiving only the necessary information for the specific task at hand through automatic index loading.

• Performs repository-wide audits of CLAUDE.md navigation hierarchies and README.md coverage.

• Enforces strict separation between operational instructions (commands, build steps) and explanatory architectural knowledge.

• Automates the creation and synchronization of tabular indices to ensure files and subdirectories are correctly indexed for AI discovery.

• Executes content migration by stripping excessive prose from CLAUDE.md and moving it into README.md to maintain token-efficient context delivery.

• Validates index integrity, identifying missing documentation and reconciling stale entries where files have been deleted or moved.

• Supports scoped execution, allowing users to trigger documentation syncs at the repository, directory, or single-file parent level.

• Designed for software engineers utilizing AI agents for long-term codebase maintenance and technical debt management.

• Requires local compliance with defined documentation conventions located in the .claude directory.

• Ideal for projects with complex directory structures where LLM attention drift is a risk.

• Excludes generated files, vendored dependencies, and git internals to prevent index pollution.

• Follows a specific workflow: Discovery, Audit, Content Migration, Index Updates, and final Verification to ensure a clean, self-contained documentation state.

• Works best when the codebase adheres to the just-in-time context principle, keeping operational metadata under 200 tokens and architectural documentation under 500 tokens.