Claude Code Skill Description Budget in Practice: Three Major Deviations Between Rules and Reality

Every turn, Claude Code hands the model a list of skill names and descriptions, which the model uses to decide when to invoke a skill on its own. This list has a budget cap, and once it overflows, some skill descriptions get dropped. A developer wrote a commit rule and an enforcement check for this in their repository, both based on official documentation, yet had never actually tested them. This week, using Claude Code 2.1.296, they finally ran a real test — and found the rules were wrong in three dimensions at once: the unit of measurement, the scope of coverage, and the reference number were all off.

According to the developer's test notes shared on DEV Community, their team set up a minimal test directory on Claude Code 2.1.296 (model claude-opus-5-5, 1M token window), keeping only .claude/skills/, running single-turn via claude -p, and reading the skill_listing attachment from the transcript to count. This experimental design bypassed the earlier "trust the summary report" approach and directly counted the list the model actually receives.

Three Deviations: Unit, Scope, and Threshold

The first deviation is the unit. The docs say the budget scales with 1% of the model's context window, but that 1% was never converted to characters; the context window is measured in tokens, while the listing budget is measured in characters. The team simply wrote 1% of 1M tokens as 10,000 characters, planting the error.

The second deviation is scope. The documented cap of 1,536 applies to both the description and when_to_use fields, but the test only reads description. No skill currently uses when_to_use, so for now they match — but any skill adding that field would slip past the check.

The third deviation is how the consequence is described. The team's rule says "skills whose descriptions are dropped will no longer trigger," but the docs' wording is that the name is preserved, the skill can still be invoked, and the model is simply "unlikely" to choose it proactively. The rule overstated the impact compared to the documentation.

Image: experiment output showing the Japanese skill set counted at 87,238 characters against a 30,000 budget, ultimately sending only 11 of 40 descriptions

What is the skill_listing budget

A "skill" in Claude Code is a declarative Markdown file, placed in .claude/skills/ or provided by a plugin or account-level configuration. Before each turn, Claude Code does not hand the model the full skill text — it sends only a listing: the skill name plus a short description, so the model can decide whether to load a skill proactively.

This listing itself consumes context window, so there's a cap; once exceeded, some skill descriptions get trimmed, leaving only the names. The key to understanding this is that the listing budget is not the entire context window but a small sub-budget within it; and it's measured in characters, not tokens, running on a separate accounting system from the model's token metrics.

Japanese Descriptions: A Hidden Cost Counted at Double

The team's skill descriptions were written in Japanese, and this turned out to be more decisive than expected.

The experiment compared two directories, each with 40 skills, each description exactly 1,000 characters — one set in English, one in Japanese. Debug logs showed the English set counted as 47,238 characters and the Japanese set as 87,238 — exactly 40,000 more, i.e., 1,000 extra per 1,000-character Japanese description. In other words, Claude Code counts each Japanese character as two.

The released listing confirmed this: the English set sent 22 of 40 descriptions, totaling 29,204 characters; the Japanese set sent only 11, totaling 18,182 characters — or 29,182 when double-counted, just under budget. With the same budget, Japanese descriptions can hold only half the number of skills that English can.

You may not have noticed, but the per-description cap is counted on a different rule. The experiment set a single skill's Japanese description to 1,997 characters, and the model received the first 1,535 characters plus an ellipsis, totaling 1,536 characters. This shows the 1,536 cap is counted by single characters, while the total budget is counted by double characters.

The encoding difference between full-width and half-width characters

In Unicode, English letters, digits, and common punctuation are half-width characters, while Japanese kana, kanji, and Chinese and Korean characters are full-width. They typically correspond to two half-width characters in visual width and often occupy 3 bytes rather than 1 under UTF-8 encoding.

This is the soil in which double-counting arises: if Claude Code internally uses something like the East Asian Width property to estimate "display width," then one Japanese character gets converted into two units. It's worth emphasizing that this is inconsistent with true tokenizer behavior — modern BPE tokenizers tokenize Japanese characters at an efficiency that varies by model and is usually far higher than the crude "one character equals two tokens" conversion. This also explains why /skill-doctor's estimate and the measured token count don't match.

What the Listing Actually Looks Like: 94% Full

The test only counted in-project skills, but the real listing also includes plugin skills, account-level skills, and Claude Code's own built-in skills.

In the main session on 2026-10-12 (Claude Code 2.1.286, Opus 5.5, 1M window), the first skill_listing attachment contained 64 entries and 26,791 characters, and every description was still present. Under the experiment's full-width double-counting rule, that's 28,119 out of a 30,000 budget — 94%.

The team's own 9 skills were only the smallest portion: 2,484 characters, 3,702 when double-counted. The 13 entries prefixed with anthropic-skills: took 9,502 characters; the 18 from Claude Code and the account took 8,094; and a memory plugin's 21 skills took 6,343. Under the experiment's counting rule, the listing had only about 1,881 units — roughly 940 Japanese characters — left, while the team's test at the time still allowed adding another 7,696 characters. The test didn't miscount its own 9 skills; it was just measuring a small slice of a budget already more than half-filled by others' skills.

Where plugin skills and account-level skills come from

Beyond the hand-written .claude/skills/ in your repository, Claude Code's listing also pulls in three external sources: official skills prefixed with anthropic-skills:, account-level configured skills, and skills installed via plugins. These skills aren't in your repository and won't be committed with the project, but they compete for the same listing budget.

This means an in-project check script has a built-in blind spot: it only sees skills in its own repository and can't perceive how much budget has already been consumed by other sources on the platform. To audit real usage, you can only read the skill_listing attachment Claude Code actually sends from the session's own transcript — because that's the listing the model truly sees.

What Five Weeks of /skill-doctor Reports Revealed

Starting 2026-09-09, the team ran /skill-doctor weekly and appended the results to state/skill-doctor-reports.jsonl. Five reports (2026-09-09, 09-21, 09-30, 10-05, 10-12) showed the listing total growing from 3,060 tokens to 3,270, and the memory plugin from 1,780 to 2,230. Invocation counts also shifted with the work: the reply-handling skill went from 16 to 54, the weekly skill from 1 to 30.

But the context column in the reports is unreliable. The team found that for the nine project entries on 10-12, the figure didn't differ from the entries' character count divided by 3 by more than 6 tokens. A 612-character English description was labeled 210 tokens, and a 162-character description that was 94% Japanese was labeled 50 tokens — a real tokenizer wouldn't treat the two the same way.

Image: experiment output showing the first request at 19,182 tokens with no project skills, 8 Japanese descriptions adding 1,508 tokens, and same-length English adding only 567 tokens

The Real Token Cost of Japanese Descriptions

To get real numbers, the team copied 8 committed Japanese descriptions into the experiment directory and compared the first-request input tokens against an empty directory. Each configuration ran twice, with repeated results differing by no more than 1 token.

The Japanese descriptions added 1,508 tokens, the English control group added 567 tokens, while /skill-doctor's estimate for those 8 lines was 610 — close to the English control group, underestimating the real cost by about 2.5×. The same held in the overflow scenario: the Japanese listing carrying 11 descriptions added 10,515 tokens, while the English listing carrying 22 descriptions added 6,921 tokens — half the descriptions yet 52% more tokens consumed.

Here, Claude Code's double-counting is actually closer to reality: proportionally, a 30,000-unit Japanese listing is roughly 15,000 characters, or about 12,000 tokens, while the English equivalent at the same budget is about 9,000 tokens — the two languages' budget token costs are in the same order of magnitude. What was truly miscalculated was the team's own test.

Why the "character count divided by 3" token estimate is skewed

Many tools use the rule of thumb "English character count ÷ 3 ≈ token count" for quick estimation. It works roughly for English text, but once Japanese, Chinese, or Korean is mixed in, it significantly underestimates. The reason is that tokenizers segment CJK text at a finer granularity, a single kanji is often split into one or more tokens, and the token tables differ considerably across models.

A more reliable approach is direct measurement: add the description under test to a single-turn claude -p request, compare the first-request input tokens between an empty directory and one containing the description, and run repeatedly to confirm stability. This article's team used exactly this method to get the real numbers of 1,508 tokens for Japanese and 567 for English, differing from the tool's estimate of 610 by about 2.5×.

Three Failures of the Test

The check can catch empty descriptions, overly short descriptions, and descriptions exceeding 1,536 characters — that part matches Claude Code's behavior. But the total count is off: Japanese characters are counted only once, so the committed 1,692 characters actually correspond to 2,894; it covers only 9 of the listing's 64 entries, with the other 55 in plugins and Claude Code itself outside the repository; and it compares against 10,000, when the real budget is 30,000. A test that passes using only a quarter of the quota has nothing to say about a listing already 94% full.

The only thing that can see the real listing is the session itself. The transcript records the skill_listing attachment Claude Code sends; counting the entries missing descriptions directly reveals the overflow, and debug logs also warn when it happens. The team hasn't yet revised the test, but they now know which number to watch — and that number isn't stored in the repository.

Implications for Developers Writing Non-English Descriptions

The core value of this test is the reminder that rules about token budgets can't be directly derived from a percentage in the docs into a character count. If your skill descriptions are in Japanese, Chinese, or Korean, or consist mainly of full-width characters, your effective listing capacity may be only half that of English users. The team calls on other developers to verify on their own machines: how many entries are in the most recent transcript's skill_listing, how many lost their descriptions, and whether Claude Code also double-counts full-width characters. This data will help determine whether the double-counting is a general mechanism or version-specific behavior.