Skill Overload Makes AI Go Blind: Claude Code and Codex Handle Overflow Differently
Installing skill (skill packages) for AI programming tools has become a daily habit for many developers. A skill is a folder containing an instruction document that specifies "when to use it and how". Each time the tool starts work, it doesn't stuff all instructions into the context. Instead, it first lists all skills' "names + one-sentence descriptions" and gives that list to the model; the model decides which to use based on descriptions, then reads the full instructions only after selecting one.
That sounds like it saves context. But what happens if you install too many skills?
Community observation: 220 of 283 skills lost their descriptions
On 2026-11-12, developer Murat Sert posted about a phenomenon: he installed 283 skills, and the list sent to the model had 220 skills with only names and no descriptions. The list length stayed stuck at about 30,000 characters (he noted that "about 30,000 characters" is an observed value, not an official spec). He also measured that before the user said anything, the first request already consumed 74,500 tokens, of which about 22,000 came from his installed plugins, skills, MCPs, and hooks; in another old session with 672 skills, 642 had no descriptions. He said he hadn't seen this mentioned in official docs.
We also checked our everyday machine (not test environment): in the last 12 sessions, each listed 120 to 125 skills, of which 54 to 60 had only names, and the list length stayed stable at 26,500 to 26,850 characters.
Actually, this is written in the official docs, and Claude Code and Codex handle it completely differently.
Budget rules in official docs
Checking both tools' official docs shows they both set a strict context budget for the skill listing:
Claude Code: Keep all names, cut descriptions of low-frequency skills first
In the "Skill descriptions are cut short" section of Claude Code docs:
- Default budget: the skill listing budget is 1% of the context window.
- Over-limit strategy: after exceeding the budget, every skill's name is kept, but descriptions are removed starting from the "least called" skill. Skills whose descriptions are removed can still be called by name, but the model is less likely to think of using them on its own.
- Single entry cap: a single description (
descriptionpluswhen_to_use) can be at most 1,536 characters in the listing; adjustable viaskillListingMaxDescChars. - Troubleshooting and logs:
/doctorshows how much context the listing occupies;/skill-doctorfinds unused skills; when the listing exceeds budget, a warning appears in debug logs (with--debug). We read this line in Claude Code debugging logs:Skill listing over budget: 315 skills, 103212 chars > 30000 budget - Adjustment: you can increase the budget in settings via
skillListingBudgetFraction(e.g.,0.02for 2%), or use environment variableSLASH_COMMAND_TOOL_CHAR_BUDGETto specify a fixed character count; you can also set unimportant skills to"name-only"inskillOverridesso they only show names, freeing budget for other skills.
Codex: Shorten each description first, then drop skills if needed
The Codex Skills page gives a different approach (note: Codex's listing also includes each skill's file path in addition to name and description):
- Default budget: listing budget is 2% of the context window; when the context window is unknown, the budget defaults to 8,000 characters.
- Over-limit strategy: after exceeding the budget, each description is shortened first; when there are too many skills, some skills are completely omitted from the listing, with a warning.
- Adjustment: you can change the budget via
skills.max_context_tokens, with a maximum of 10,000 tokens. The docs specifically recommend putting key uses and trigger words at the very front of the description, so matching still works after description shortening.
Our practical comparison
How much difference do these two truncation strategies make in actual work? We tested on 2026-11-13.
Test environment and method
- Versions and models: Claude Code
2.1.323, Codex CLI0.162.1(not the latest at the time), both with default models. No personal config or personal skills loaded at runtime; only skills in the test directory were loaded. - Test task: install a target skill whose description contains "use when user wants to generate an invoice number", with full instructions specifying a team-specific number format. Then tell the tool only "generate an invoice number"; only if the output matches that format is it a successful trigger. Each condition ran 3 times.
- Interference condition: added 300 unrelated fake skills, each with a description of about 160 characters, covering administrative matters unrelated to invoices (inventory counts, conference room bookings, travel reimbursements, etc.). The target skill was placed last in the listing. On Claude Code, all test skills had never been called, so which descriptions got removed was determined by the order.
- How listings were obtained: Claude Code's listing was read directly from session records; Codex's listing was obtained by having Codex itself write out what it saw, not read from logs.
Core results
| Condition | Claude Code | Codex |
|---|---|---|
| Only this one skill | 3/3 triggered, ~8-10 seconds | 3/3 triggered, ~21-25 seconds |
| Add 300 unrelated fake skills | 1 of 3 triggered | 3/3 triggered, ~22-25 seconds |
Note: time differences include model and startup time; cannot be attributed solely to the skill mechanism.
With only this one skill, Claude Code had ~41k input tokens, Codex ~49k. After adding 300 fake skills, the two diverged:
- Claude Code (1 of 3 triggered): listing had 315 entries, 237 had only names, and the target skill at the end also lost its description.
- The 2 failed runs: it didn't call any tool; it just made up a number (
INV-20261113-0001) and returned it, with ~32k input tokens. - The 1 successful run: it first searched the skill folder for "invoice", found it, then used it. This run consumed ~137k input tokens, more than double normal (compared to ~67k when directly triggered).
- The 2 failed runs: it didn't call any tool; it just made up a number (
- Codex (3/3 triggered): ~57k input tokens. Each description was shortened to around 25 characters; the target skill's description remained "use when user wants to generate an invoice number. Give the invoice number format agreed by this team" (roughly) – core keywords survived, so the model still recognized it.
Three other interesting observations
- A distinctive name gets guessed: early in testing, the target skill's name looked different from the 300 fake names. Even with description removed, Claude Code used it in all 4 runs, 3 times by directly clicking on the name that "looked different". The table data above is from rerunning after changing the target name to the same format as the fake names.
- Once used, the description returns: in Claude Code, after a skill is called once, in a fresh run under the same environment, its description reappears in the listing. This matches the official "remove least-called first" rule.
- Codex's failure point comes later: when fake skills increased to 1,500 (this condition ran only once), Codex warned that all skill descriptions were removed, and another 654 skills didn't make it into the listing. The target skill wasn't in the listing, so it didn't trigger; it also made up a number.
Test limitations
- Each condition ran only 3 times (the 1,500 fake skill condition ran once), a small sample.
- The target skill's keywords happened to be at the very front of the description, which favored Codex's "shorten description" approach; the case where keywords are in the second half wasn't tested.
Practical advice you can follow directly
Based on official docs and test results, if you have many skills installed, optimize with these points:
- Put keywords first: write "when to use" as the first sentence of the description, putting core trigger words at the very front. This preserves matching even when Codex shortens descriptions.
- Make skill names reveal their purpose: in the extreme case where descriptions are trimmed and only names remain, a semantically clear name still helps the model guess the right tool.
- Clean up idle skills: disable or uninstall unused skills promptly. In Claude Code, use
/doctorto see context usage of the listing,/skill-doctorto find unused skills, or set low-priority skills to"name-only"inskillOverrides. - Increase budget as needed: in Claude Code, frequently used skills naturally keep their descriptions because they are called often; if you truly need many skills on standby, increase
skillListingBudgetFractionin Claude Code settings (or configureSLASH_COMMAND_TOOL_CHAR_BUDGET), and adjustskills.max_context_tokensin Codex.
Reference links
- Murat Sert's article: https://dev.to/msertdev/i-measured-what-my-claude-code-setup-costs-on-every-request-most-of-my-skills-had-gone-blank-2eg3
- Claude Code docs (Skill descriptions are cut short): https://code.claude.com/docs/en/skills
- Codex docs (Skills): https://developers.openai.com/codex/skills
Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.
54 to 60 skills left with only their names; the root cause is often that everyone installs their own and never uninstalls. Our team later maintained a single shared config, with a couple of tech-savvy people responsible for adding and removing, while others use it directly. Someone takes responsibility for the whole list when deciding which skill should be dropped. According to the rule in the article about Claude Code 'trimming descriptions starting from the least-called', rather than each person adjusting their budget, it's better to centralize the management of the list.
What model are you? 😏