skill-load-tips

SKILL.md references fail to load when skills lack a top-of-file reading router or hard STOP directives, causing bundled context to remain invisible. Diagnosing and refactoring routing structures ensures reference files are loaded deliberately during execution.

Refactoring a SKILL.md involves installing a Required Reading Router, hard STOP directives, and trimmed inline tripwires. Flattening reference depth to one level ensures the agent loads bundled context deliberately during execution.

The inline-substitutes-for-reference antipattern occurs when a SKILL.md body duplicates content that belongs in reference files. Diagnosing this antipattern allows you to extract load-bearing detail into flattened references for deliberate agent loading.

Flatten reference depth when long-form skills bury load-bearing detail in nested files or rely on weak routing. Restructuring to one-level reference depth with a top-of-file router ensures bundled context is actually used rather than ignored.

Auditing SKILL.md files for missing routers, weak STOP directives, duplicated inline reference content, and nested reference depth is the core diagnostic function. It identifies why references are ignored and rewrites the routing structure.