We moved our Claude Code skills' reference.md files back into SKILL.md. Was that the wrong call?
On 2026-09-18 we took the reference.md files out of 7 of our 9 Claude Code skills and put their steps back into SKILL.md , against the docs' advice to split. Today our 8 skills are one file each, 107 to 421 lines. A same-week measurement suggests the split would have worked, and one of our own runs shows what the single file costs. This is a question post: how do you split yours? What we had, and…
On September 18, 2026, the reference.md files from seven out of nine Claude Code skills were moved back into SKILL.md, contrary to the documentation's advice to split them. Currently, each skill consists of a single SKILL.md file, ranging from 107 to 421 lines in length. The largest file is 421 lines long and written in Japanese.
When a skill is invoked, its SKILL.md content is presented as a single message and remains available throughout subsequent turns. After a compaction, Claude Code keeps only the first 5,000 tokens of each skill, with a shared pool of 25,000 tokens. In a test of 20 Claude-p runs on a small skill, bundling the reference.md file did not result in any skipped steps, even when it was read in 16 out of 16 runs where it was pointed to by SKILL.md.
However, the test was conducted on a small skill with a single task, and no tests have been performed on the longer, more complex skills in use. The author is questioning whether keeping everything in a single SKILL.md file or splitting it into reference.md and other files is the better approach, and is seeking insights from others who have implemented either method.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
