agent-md-refactor

To refactor a monolithic AGENTS.md file, this Skill restructures the content into a minimal root document and links detailed sections under a standardized .kiro guidance layout, applying progressive disclosure to keep navigable docs modular.

Progressive disclosure for agent instruction files is the practice of minimizing the root document to essentials while linking to detailed subdocuments, which streamlines oversized policy files into scalable, organized guidance for easier maintenance and onboarding.

You can break down a bloated CLAUDE.md file by applying root minimalization, extracting verbose sections into linked subdocuments, and organizing the remaining guidance into a progressive file structure that teams can easily navigate and govern.

Yes, this approach supports the standardized .kiro guidance layout, organizing extracted subdocuments from monolithic instruction sets into a modular, navigable documentation system that aligns with your existing progressive file structure.

You should refactor agent instructions into linked subdocuments when oversized files become difficult to maintain, onboard, or govern, and your team needs to rewrite monolithic policy files into scalable, organized guidance.

The best way to organize agent instructions for easier maintenance is to rewrite monolithic policy files into a minimal root with linked sections, applying progressive disclosure to create a scalable, navigable documentation system.