instruction-file-splitting

To prevent context compression from dropping agent rules, split long markdown files into a short parent router and topic-owned sub-files. This ensures iron rules remain in the parent and later rules are not silently lost by model context limits.

You should split agent instruction markdown when files reach 280–300 lines, when edits would cross that boundary, or when deep nesting and duplicated hard rules threaten coherence. Splitting keeps parent files under 150 lines and sub-files under 300.

The best way to manage MUST and NEVER rules during documentation splitting is placing these iron rules at the very top of the parent router file. You must prevent duplication across sub-files to maintain rule enforcement and coherence.

Route agents to the correct sub-file by creating a concrete read when pointer table in the parent router. This on-demand detail routing ensures the agent loads the right depth only when a specific situation occurs.

Yes, instruction file splitting works with existing SKILL.md agent workflows by refactoring the long instruction document into a short parent router and topic-specific references. It applies when the SKILL.md is near or above 300 lines.

Limitations of splitting markdown instruction files include the strict requirement to keep the parent under 150 lines and sub-files under 300. You must also avoid vague pointers and duplicated rules across files to prevent coherence issues.