Test zeigt: Skill-Beschreibungen in Claude Code erreichen 94 Prozent des Limits

Our commit test caps the combined length of our skill descriptions at 10,000 characters, and we sit at 2,304. On Claude Code 2.1.296 the real listing budget for a 1M-token window is 30,000, a Japanese character counts as two against it, and by that count the whole listing our agent received was already at about 28,100, while /skill-doctor priced our eight Japanese descriptions at 610 tokens when they actually added 1,508.

Every turn, Claude Code puts a listing of skill names and descriptions in front of the model, and the description is what the model reads when it decides on its own to use a skill. The listing has a budget. When it overflows, some descriptions are dropped. Our repository has a written rule about that budget and a test that enforces it before every commit, and both were written from the documentation, not from a measurement. This week we measured them against what Claude Code actually sends. The rule turned out to be off in three ways at once: it counts in the wrong unit, it covers the wrong part of the listing, and it compares against the wrong number.

Our skill descriptions are written in Japanese. That turned out to matter more than anything else here, and it's the part we'd most like other people to check on their own machines.

Our rules file for skill authors,.claude/rules/claude-md.md, says in Japanese that the descriptions of all skills together must stay within 10,000 characters. It gives the reason in the same sentence: Claude Code's listing has a character budget of 1% of the model's context window, our main session and our subagents all run with a 1M-token window, and over budget, Claude Code cuts descriptions starting from the least-invoked skills, which then stop firing. The same line caps each description at the official 1,536 characters.

The check lives in src/quality/gates/claude-md-structure.ts and runs from test/ops/claude-md-structure.test.ts, which is part of our commit gate. The limits are three constants:

export const SKILL_DESCRIPTION_TOTAL_MAX_CHARS = 10 _000 export const SKILL_DESCRIPTION_MAX_CHARS = 1 _536 export const SKILL_DESCRIPTION_MIN_CHARS = 40 Enter fullscreen mode Exit fullscreen mode and the total is a plain sum over every folder under.claude/skills:

The git history of that file tells the rest. The checks arrived on 2026-09-07, in commit bbf0dc95, prompted by a reader's comment. The first cap was 2,000 characters, with a code comment calling it 1% of a 200K window. That evening our nine skills totaled 1,885 characters. The next day a tenth skill took the total to 1,990, ten characters under the cap. On 2026-09-27, commit 567a49c7 raised the cap to 10,000 with the owner's approval; the new comment says the main session and every subagent run on 1M windows and nothing runs on a smaller one. The same commit deleted a skill, and after the merge that followed, the committed total was 1,692. It still is: eight skills, with descriptions between 145 and 293 characters.

Our working tree also has a ninth skill folder that git ignores, a skill we were trying out locally, with a 612-character description written mostly in English. The test lists every folder, ignored or not, so on our machine it sums 2,304 and on a fresh clone 1,692. Either way it passes with room to spare.

We fetched the skills page and the settings reference on 2026-10-13 at 19:11 UTC. The skills page, under "Skill descriptions are cut short", says:

The listing always contains every skill name, but if you have many skills, Claude Code drops some descriptions to fit the listing's character budget, which removes the keywords Claude needs to match your request. The budget scales at 1% of the model's context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text.

A few lines further on it adds: "put the key use case first, since each entry's combined text is capped at 1,536 characters regardless of budget." The settings reference describes skillListingBudgetFraction with a default of " 0.01, which reserves 1% of the context window", and says what an overflow costs: "When the listing is over the cap, Claude Code keeps every skill's name but drops the descriptions of the least-used skills, so Claude can still invoke those skills but is less likely to choose one on its own." The per-entry cap is skillListingMaxDescChars, default 1536, and "longer text is cut at the cap."

So the docs and our rule agree on 1% and on 1,536, and differ in three places.

First, the docs never turn 1% into characters. The context window is counted in tokens, and the budget is counted in characters. Our rule took 1% of a million tokens and wrote it down as 10,000 characters.

Second, the docs' 1,536 cap applies to description and when_to_use together. Our test reads only description. None of our skills uses when_to_use today, so the two agree for now, but a skill that added one would get past our check.

Third, our rule says a skill whose description is dropped stops firing. The docs say the name stays, the skill can still be invoked, and the model is "less likely" to choose it on its own. Our rule states it more strongly than the docs do.

To see the real number, we built a small lab: fresh directories holding nothing but.claude/skills/, run with Claude Code 2.1.296 as claude -p "Reply with the single word OK." --output-format json --model opus --setting-sources project --max-turns 1, with a debug log file. The JSON reported the model as claude-opus-5-5 with a context window of 1,000,000. Each session records the listing it sent in its transcript as a skill_listing attachment, so we counted entries there instead of trusting a summary.

The first pair of directories held 40 skills each, every description exactly 1,000 characters. In one set the text was an English sentence repeated; in the other, a Japanese sentence with the same meaning, repeated and cut to the same length.

Every run of both sets wrote the same kind of warning to the debug log, [WARN] Skill listing over budget: 54 skills, … chars > 30000 budget, where 54 is our 40 plus Claude Code's own 14. The budget for a 1M window at the default fraction is 30,000. The English set was counted at 47,238 characters and the Japanese set at 87,238: exactly 40,000 more, or 1,000 extra for each 1,000-character Japanese description. Claude Code counted each Japanese character as two.

The listings that went out match that. The English one carried 22 of the 40 descriptions in 29,204 characters. The Japanese one carried 11 of the 40 in 18,182 characters, which comes to 29,182 if each Japanese character counts as two, just under the budget. Repeat runs of both sets sent identical listings. With the same budget, Japanese descriptions fit half as many skills. The doubling is what a terminal does when it measures display width, where a full-width character takes two columns. We didn't read Claude Code's source to confirm that is the mechanism, and we only tested Japanese, not Chinese or Korean.

The per-entry cap counts differently. We gave one skill a 1,997-character Japanese description ending in a marker. It arrived as its first 1,535 characters followed by …, 1,536 characters in all, and the marker was gone. By the doubled count that entry was 3,071. So the 1,536 cap counts characters the way our test does, while the total budget counts a Japanese character twice.

Our 10,000 is therefore a third of the real budget, and our first cap of 2,000 for a 200K window was a third of what the same arithmetic gives for that window, 6,000. That sounds like a comfortable margin. It wasn't, for a reason the test can't see.

The test sums our project skills. The listing holds everything: plugins, account-level skills and Claude Code's own. In our main session on 2026-10-12, which ran Claude Code 2.1.286 on Opus 5.5 with a 1M window, the first skill_listing attachment had 64 entries in 26,791 characters, and every entry still had its description. Counting each full-width character as two, which is the lab's rule applied by our own script (we didn't re-test it on 2.1.286), that is 28,119 of 30,000, or 94%.

Our own nine entries were the smallest part of it: 2,484 characters, 3,702 by the doubled count. Thirteen entries under an anthropic-skills: prefix, covering documents, browser control and research, took 9,502. Eighteen that come with Claude Code or with our account took 8,094. A memory plugin's 21 skills took 6,343, and three small plugins took 478 by the doubled count.

Put the two numbers side by side. By the lab's counting rule, the listing had about 1,881 units left, roughly 940 more characters of Japanese description, before Claude Code would start dropping something. Our test, at that moment, would have let us add 7,696 more characters. The test wasn't wrong about our nine skills. It was measuring a slice of a budget that other people's skills had mostly filled already.

The docs say the least-invoked skills lose their descriptions first. Our latest /skill-doctor report shows 19 memory-plugin skills and our locally ignored one at zero invocations, so an overflow would probably take those before any skill we use. We haven't checked that Claude Code ranks skills by the same counts the report shows, so that is a reading of the docs, not a measurement.

Since 2026-09-09 we have run /skill-doctor about once a week and appended its table to state/skill-doctor-reports.jsonl with pnpm skill-doctor-report. There are five reports so far, dated 2026-09-09, 09-21, 09-30, 10-05 and 10-12, from Claude Code 2.1.277 to 2.1.296; the first was transcribed by hand. The listing totals were 3,060, 3,210, 3,160, 3,270 and 3,270 tokens across 40, 40, 35, 36 and 36 rows, and our project rows made up 720, 660, 820, 820 and 820 of them.

The memory plugin grew from 1,780 to 2,230. Invocation counts moved the way the work did: the skill that handles replies went from 16 to 54, the reach skill from 20 to 54, the weekly skill from 1 to 30, and the subagent-rules skill from 0 to 4. The seven-day token column was too jumpy to rank anything on by itself; for the weekly skill it read empty, empty, 344.1M, 1.2B and 245.9M.

The context column is the one that bears on the budget, and it doesn't count tokens the way the model does. The docs describe /doctor 's figure as "an estimate of the listing's context cost" and don't say how /skill-doctor computes its per-skill column. For all nine of our project rows on 2026-10-12, the figure is within 6 tokens of the entry's characters ( - name: description ) divided by three, and the report rounds to tens. That holds for the mostly English 612-character description (638 characters, 210 tokens) and for a skill whose description is 94% Japanese (162 characters, 50 tokens). A real tokenizer wouldn't treat those two alike.

To get the real figure, we copied our eight committed SKILL.md descriptions verbatim into a lab directory and compared the first request's input tokens against an empty directory: input plus cache creation plus cache read, as the JSON reports them. Then we built a control with the same eight names and, for each one, English filler cut to the same character count.

Each configuration ran twice, and the repeats agreed within one token. Our Japanese descriptions added 1,508 tokens, the English control added 567, and /skill-doctor had put the same eight rows at 610. The listing grew by 1,845 characters in the Japanese run, about 1.2 characters per token, against about 3.2 for the English. The report's figure matches the English control, and it underestimates what our real descriptions cost by a factor of about 2.5.

The over-budget runs show the same thing at scale. The Japanese listing, carrying 11 descriptions, added 10,515 tokens over the empty directory, and the English listing, carrying 22, added 6,921. That is half the descriptions for 52% more tokens.

There is one fair point in Claude Code's favor here. Its doubled count is closer to what Japanese costs than our test's single count. By plain arithmetic from those ratios, a 30,000-unit listing of Japanese is about 15,000 characters and roughly 12,000 tokens, and the same budget filled with English is roughly 9,000 tokens. The doubling doesn't make Japanese free, but it keeps the token cost of the budget in the same range for both languages. Our test, counting one per character, is the one that misses.

The test does catch a skill whose description is empty, too short or over 1,536 characters, and that part matches what Claude Code does. The total does not. It counts a Japanese character once where Claude Code counts it twice, so our committed 1,692 characters come to 2,894 by the doubled count. It covers 9 of the 64 entries in the listing, and the other 55 live in plugins and in Claude Code itself, outside the repository, where a commit test can't read them. And it compares against 10,000 when the budget is 30,000. A test that passes with three-quarters of its allowance unused said nothing about a listing that was 94% full.

What does see the real listing is the session itself. The transcript records the skill_listing attachment Claude Code sent, so counting entries without a description there would show an overflow directly, after the fact, and the debug log warns at the moment it happens. We have not changed the test yet. We now know which number it should watch, and that number isn't stored in the repository.

If you write skill descriptions in Japanese, Chinese or Korean, or install a lot of plugin skills, we'd like to know what your listing looks like: how many entries were in the last skill_listing attachment in one of your transcripts, how many had lost their descriptions, and whether your Claude Code counted full-width characters twice the way ours did. Tell us in the comments below. We'll compare your numbers with ours there.