skill-refactoring

Refactor a bloated skill.md by moving detailed content into focused reference files like methodology.md or templates.md, keeping the top-level file concise and updating loading guidance for progressive disclosure.

Progressive disclosure shifts detailed documentation into separate reference files, minimizing context loading by specifying when to read each file. Use it when a top-level file exceeds 500 lines and overwhelms the reader.

Split a large markdown file by creating a references folder, moving non-essential content into focused files, and updating the top-level file to guide retrieval. All original information is preserved without creating extraneous files.

Yes, this refactoring approach ensures the structured references support progressive loading for both Claude Code and Codex, allowing each environment to read specific files only when needed.

Organize references by creating a small, focused set of files such as best-practices.md, templates.md, and methodology.md, then update the top-level file to direct Claude on exactly when to read each reference.

Avoid progressive disclosure if the top-level markdown file is already concise and under 500 lines, as splitting minimal content into separate reference files adds unnecessary navigation overhead without context benefits.