agent-md-refactor

Refactoring agent instruction files using progressive disclosure splits monolithic configurations into a minimal root file and linked, categorized sub-files. It extracts essential information for the root file, categorizes remaining instructions into separate markdown files, and flags redundant content for deletion.

The best way to organize large instruction files like CLAUDE.md is progressive disclosure, which creates a concise root file with links to separate markdown files for specific guidelines like TypeScript, testing, or code style, improving maintainability and readability.

Yes, contradiction detection is supported during the refactoring process. The Skill analyzes the original monolithic file to identify conflicting instructions before extracting essential information and categorizing the remaining instructions into linked markdown files.

Splitting a 500-line CLAUDE.md involves analyzing the file, extracting essential instructions for a minimal root file, and categorizing the remaining content into linked markdown files for specific topics like testing and code style, while flagging redundant content for deletion.

Refactoring agent instructions into linked markdown files improves code organization by applying progressive disclosure principles. This approach enhances the maintainability and readability of agent configurations by replacing monolithic files with a structured, categorized format.

Progressive disclosure for agent instruction files may not suit small, simple configurations that do not suffer from maintainability or readability issues, as the overhead of creating linked markdown files outweighs the organizational benefits for minimal content.