跪拜 Guibai
← All articles
AI Programming · Claude

Skill Overload Makes AI Go Blind: Claude Code and Codex Handle Overflow Differently

By ZzT ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Skill-heavy setups can silently degrade AI coding tool reliability: one tool stops finding the skill it needs while another still works. The budget rules turn skill naming and description wording into prompt engineering, and knowing them tells you how to clean up and reorder before your assistant goes blind.

Summary

Installing many skills into an AI coding tool is common, but the skill name-and-description listing has a hard budget. Claude Code caps it at 1% of the context window, Codex at 2% (or 8,000 characters). When overflow happens, Claude Code preserves all skill names and removes descriptions starting from least-called skills, while Codex shortens every description first and then drops whole skills if needed.

A direct test with a target invoice-skill plus 300 unrelated fake skills showed the difference: Claude Code triggered the target only once in three runs, and when it failed it invented a number without calling any tool; Codex triggered all three times because its truncated description still contained the core trigger phrase. A distinctive skill name let Claude Code guess the target even without a description, and a called skill gets its description restored in later sessions. At 1,500 fake skills, Codex finally failed, dropping the target from the listing.

Takeaways
— Claude Code's skill listing budget defaults to 1% of the context window; Codex's defaults to 2% (or 8,000 characters when the window is unknown).
— In overflow, Claude Code retains all skill names but removes descriptions from least-called skills; Codex first shortens each description, then omits skills entirely.
— In a test with 300 unrelated skills, Claude Code triggered the target skill once in three runs; Codex triggered all three.
— On the failed runs, Claude Code invented an invoice number without calling any tool; on the one success, it searched the skill folder and used ~137k input tokens, double the normal cost.
— Codex shortened each description to about 25 characters, preserving the target's front-loaded keywords and still recognizing it.
— A skill with a distinctive name got picked by Claude Code 4 of 4 times even with no description, so name clarity matters.
— After a skill is called once in Claude Code, its description reappears in the listing on subsequent runs.
— At 1,500 fake skills, Codex removed all descriptions and omitted 654 skills from the listing; the target didn't trigger and Codex fabricated a number.
— Claude Code's `/doctor` and `/skill-doctor` were used to inspect listing context and find unused skills.
Conclusions

Truncation is not just a token-saving detail; it decides which tools the model can discover at all, so writing a skill description becomes an exercise in surviving a character budget.

Claude Code's approach favors keeping every skill addressable by name, but that leaves it fragile when many skills compete for a 1% slice; Codex's uniform shortening preserves each skill's core trigger phrase but erases nuance.

The test's three-run sample is too small to be definitive, but the failure pattern lines up with the documented budget rules, so the risk is real for large skill libraries.

The fact that a used skill gets its description restored in Claude Code suggests the tool tracks per-session usage and rewards active skills, which could guide how developers prioritize what stays installed.

Concepts & terms
skill
In AI coding tools, a skill is a folder with an instruction document that tells the model when and how to use a capability; the tool lists skill names and descriptions to choose from.
skill listing budget
A cap on the combined token or character count of the skill name-and-description list injected into context. Overflow triggers truncation rules.
skillOverrides
A Claude Code setting that forces a specific skill to appear name-only in the listing, freeing budget for other skills.
skillListingBudgetFraction
A Claude Code configuration that changes the skill list budget as a fraction of the context window (e.g., 0.02 for 2%).
skills.max_context_tokens
A Codex setting that raises the skill listing budget up to 10,000 tokens.
From the discussion
Featured comments
shushenghong

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.

ZzT

What model are you? 😏

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗