Your skill file is too big: the 6KB line, measured

Skill files — the markdown instruction files coding agents load at runtime, whether you call them SKILL.md, AGENTS.md, or rules — have a size limit nobody talks about. Keep yours under 6KB. That is the finding; everything below is the evidence.

We got here by accident first. During an unrelated experiment, a 9,211-byte skill file, written in one pass by the model itself the way most people write these files, made our weaker model return empty responses six times in a row inside the test driver. We reran it with the output budget raised to 16,000 tokens. Still one empty out of two. The file was not buggy. It was just long, and the model was spending its entire output budget thinking about it.

So we stopped treating it as an anecdote and measured it.

This is part 3 of a series, and it stands alone if you only want the number. Part 1 is the kill rule that fired; part 2 is the map of where skills help, do nothing, and backfire.

The experiment: one variable, 28 executions

The setup was deliberately boring. Same task throughout: extract an invoice batch, with three private conventions buried in the skill file (prices in cents that must convert to dollars, a 6% channel fee, a tax-exempt line item listed separately). Same system prompt. max_tokens pinned at 16,000. No retry on empty outputs, because retries hide the raw failure rate we wanted to see.

The only thing that changed was file size. We took a compact 2,761-byte skill and padded it toward target sizes using 54 real bloat blocks harvested from that naturally bloated 9.2KB file: repeated sections, restated rules, ceremonial boilerplate that models actually produce. No random filler. Seven size points, four repetitions each: 28 executions. Scoring was deterministic regex against the three conventions, no judge model involved.

We also wrote down the falsification line before running: if empty-output rate and token consumption do not rise with size, the 9.2KB incident was a one-file coincidence.

One unit note, because reviewers will ask: we measure the file in bytes because that is what you see in your editor. At roughly four characters per token of English, 6KB is about 1,500 tokens of instruction text. The file rides in the prompt as input, but its length inflates the model's output-side thinking, and that thinking is what hits the 16,000 cap. The input side is not free either: an agent loop re-reads the whole conversation on every iteration, so every kilobyte that stays resident charges rent on every request. We audited one production pipeline whose daily spend grew from 110 million to over 500 million tokens with no change in workload, and the skill catalog alone had quietly reached 161KB of every system prompt.

What happened

Two regions are visible to the naked eye. Below 6KB, the model consumed 8–9K tokens per run, comfortably far from the cap, and never returned empty. At 6KB and above, consumption got pushed into the 12K–15.5K neighborhood of the 16,000 ceiling, and a quarter of the runs died there. The 9.5K point averaged 15,469 tokens, kissing the cap, and two of its four runs survived only because the thinking chain happened to come in shorter. Whether you crash at the edge is decided by variance in reasoning length, not by anything you control.

The rules, stated precisely

The tempting summary is "bigger file, more deaths." The data says something more specific:

1. Under 6KB is a safe zone. Eight runs at 2.8K and 4.1K, zero empty outputs, consumption far from the cap.
2. At 6KB and above you are in a risk zone. Burnout is a function of how close your consumption rides to the output cap, not a monotone function of file size. Near the cap, survival is luck.
3. The 11.2K point breaks monotonicity. Zero empties, consumption back down to 9,927. That variant contained all 54 blocks, including the natural file's own structured sections. Our working hypothesis is that organized content partially compensates for raw size. Unverified; we flag it because deleting the counterexample would make the chart prettier and the claim wrong.
4. Organic bloat is the most poisonous kind. Same size class, different file: the naturally bloated 9.2KB file died at 50% where the hand-padded 9.5KB died at 25%. Repetition and rambling hurt more than bytes. This also retroactively explains the original incident: six consecutive empties was not bad luck, it was a 50% failure rate behaving normally.
5. Size kills production, not correctness. When the model did produce output, convention hit rates stayed near full at every size point. The question a long file answers first is not "will the model follow it" but "will the model answer at all."

What to do with this

Three rules we now apply to our own skill files, AGENTS.md, and long system prompts:

Budget under 6KB. Not as a style guideline; as an executability zone. Our generation pipeline now treats 6–9KB as risk territory (25% observed failure) and 9KB+ as high risk, and the audit step fails files that drift over.

Delete repetition before deleting content. The natural file's problem was not that it said too much; it said everything twice. Deduplication recovered more safety than trimming rules did in our padding exercise.

Budget tighter for weaker models. These runs used DeepSeek V4.1-Flash as the execution model, and weaker models are exactly where the cliff matters: stronger models burn budget more gracefully, and the same file can hurt one model and not the other. The full strength-dependency map is in the companion piece.

Honest limits

One task (invoice extraction), one model family, four repetitions per point, so the 95% confidence interval on "25%" is wide, and padded-via-algorithm is not identical to bloated-by-handwriting. The 11.2K counterexample deserves a direct test we have not run yet: hold byte count fixed, vary structure, organized filler against rambling filler. The gradient round cost ¥2.55 in API fees, about $0.36. Replicate it before you tattoo 6KB on anyone; treat it as a measured starting point with a clear mechanism, not a universal constant. But "the model returned nothing because it spent its whole budget reading your instructions" is a failure mode worth checking today, with the file sizes you already have. wc -c is the whole diagnostic.

The series, in order

1. We pre-registered a kill rule for our own product. It fired.: the program this gradient round belongs to
2. Same skill, opposite effects: when structure helps, when it does nothing, when it backfires
3. The 6KB line (you just read it)

Beyond the series: AGENTS.md as a token budget, the forbidden-list playbook for the file you already maintain; Same prompt, four thinking budgets, four bills, the metered version of what output-side thinking costs.

The tool behind this series is open source: Skill Forge ships as an MCP server, a prompt pack, and an installable skill, under MIT + Commons Clause. Design deep-dive right here on dev.to: We open-sourced the tool that failed its own kill rule.

Disclosure: Wallaby Token (that's us) sells API access to open-weight models. This experiment ran on DeepSeek V4.1-Flash, and nothing in it depends on where your API key comes from.