reference-creation

To organize complex documentation with too many patterns, create a structured references/ directory containing topic-specific guides. This modular approach splits sub-topics into focused files, improving readability and enabling targeted study instead of overwhelming learners in a single document.

You should split documentation into modular reference files when your main SKILL.md grows too long or contains 40+ patterns. This enforces consistent naming and cross-linking conventions, preventing deep knowledge from overwhelming learners in a single document.

The best way to structure a references directory is creating a README.md for navigation alongside 4 to 9 topic files. Descriptive naming delineates sub-topics, while cross-links between files support quick navigation and consistent organization.

Cross-link navigation between modular reference guides by applying standardized conventions for linking from the main file to topic-specific guides, and connecting the reference files themselves to ensure consistency and ease of navigation.

Splitting documentation into topic-specific guides improves readability by enabling targeted study and efficient token usage. Focused reference files prevent overwhelming learners, ensuring deep knowledge remains navigable and accessible.

Keeping complex skill patterns in a single document overwhelms learners and hinders navigation. Without a modular references directory, discovering specific sub-topics becomes difficult, and token usage increases inefficiently during targeted study.