Does the agent actually read my SKILL.md all the way to the end? I'd left that question fuzzy for a long time. Writing article-generation skills for four technical blogs, my SKILL.md kept growing: cautions, banned patterns, quality-gate explanations, handoff steps to other skills. Before I knew it, it had passed a thousand lines. Then an observation report hit home.
When Codex CLI reads a SKILL.md, the logs showed commands shaped like sed -n '1,220p'. For a 441-line skill, the back 221 lines never make it into the output. And across many tasks, the deepest line read lined up at right around 220, reproducibly. For anyone running these in production, that's a hard-to-ignore signal that the SKILL.md you think you wrote and the SKILL.md the agent actually reads may be two different documents.
Why it stops at 220
You'd want to blame a CLI bug at first. But the observation concluded otherwise. Codex CLI has no dedicated file-read tool, so reading a file is the same as generating and running a shell command. On the path where the agent picks a skill from natural language, "read the SKILL.md body" becomes "run sed." And the sed -n '1,220p' string was assembled by the model, not the harness.
So why around 220 every time? The observer's read is that 220 is the length the model assumes a SKILL.md to be. Reading ordinary code files yields varied line counts, but reading a skill is a single, repeated situation. The Agent Skills standard keeps the body short by design, offloading long specs and samples to references/ and writing only "when to use" and "how to proceed" in the SKILL.md itself. A spec-compliant SKILL.md tends to land around 200 lines, so "a reasonable skill's length plus some margin" surfaces near 220.
The key point: this isn't an instruction to "cut off at 220." It's the model's idiom for "read an entire SKILL.md in one go." Written short per spec, the whole thing is read even at 220. Trouble only appears for skills that exceed the assumed length.
The behavior depends on the harness
This is easy to misread, so a note. The cutoff doesn't happen everywhere. On skill-tool harnesses, like Claude Code, where the harness reads the full body in advance and hands it to the model, sed never appears, so this cap stays hidden. The observation reports that on the Claude Code path, a 441-line skill was delivered at 441 lines every time.
The core of the problem, then, isn't "the Codex tool" but the architecture shape of "if you read a file, the model writes the shell command." If you want your skill used across multiple agents including Codex, the safe move is to write to the most conservative assumption. And that conservative assumption turns out to be exactly what the original spec said: keep SKILL.md short.
What tends to live in the back half
What made me break a sweat reviewing my own SKILL.md was precisely the content I'd placed in the back half. The observation notes that what sat past line 220 was anti-patterns, expected drift patterns, the stop condition, and handoff steps to other skills, in other words, the strongest instructions: "don't get sloppy this way" and "stop once you reach here."
It's an ironic structure. The very text meant to stop or course-correct an agent is what you want to gather at the end for safety. But that "stop" side is exactly what goes unread when placed late. My own article-generation skill clustered the quality-gate banned patterns and pre-push checks at the end, so in a cross-agent context it likely fell into the same hole.
How to keep it under 200 lines
The fix isn't changing the tool; it's matching the model's assumption. The measured value was 220, but it's a margin-inclusive number, so if you draw your own limit, 200 is safer. Concretely, three things.
- Keep the SKILL.md body under 200 lines.
- Put the Iron Law, when to use, core procedure, and minimal examples in the first 200 lines.
- Offload long examples, anti-patterns, and reference docs into references/.
Offloading to references/ isn't just about cutting line count. It's progressive disclosure itself. At startup, only each skill's name, description, and path load; the body is read when the skill is chosen. Finer specs are read individually from references/ by the agent that needs them. Put "when and how" in the body and "the detail" in references/, and you ride this disclosure flow naturally.
As an indie developer who has built apps since 2014, after I re-split my four-site operations skills into "body holds judgment and procedure, detailed docs live in separate files," the skills started firing as intended. Back when I crammed everything into a thousand-line body, articles sometimes slipped through where the crucial banned patterns hadn't taken effect.
What you can check today
If you have a long SKILL.md on hand, count the body's lines first, and if it's over 200, check whether the Iron Law and stop condition are in the first 200 lines. If not, you can start by moving that part to the top and shifting long examples and anti-patterns into references/.
Unless the SKILL.md you wrote and the one the agent reads are the same length, they're different documents. With that in mind, I went deeper on stabilizing output with templates and decision guides in designing skills that stabilize output. For orchestrating with a script instead of a skill, what I learned about orchestrating subagents should help.
Thank you for reading to the end.