You wrote a SKILL.md. You installed it. /skills lists it. You ask Claude Code to do the exact thing the skill was built for, and nothing happens. The model answers from scratch, ignores the file, and you start questioning whether description fields even matter. If your Claude Code skill is not loading despite being correctly placed in ~/.claude/skills/, the cause is almost never a parse error. It is a token budget you did not know existed.
Claude Code allocates roughly 1% of the model's context window to skill metadata at session start. On a 200K window that is around 2,000 tokens, give or take, controlled by the skillListingBudgetFraction setting introduced in Claude Code 2.1.129 (default 0.01). The per-skill description cap inside that listing is 1,536 characters via skillListingMaxDescChars. (code.claude.com/docs/en/skills, claudefa.st)
If the total name + description payload for all installed skills exceeds that fraction, the lowest-priority entries are silently dropped from the listing. The skill is still installed on disk. /skills still shows it. Claude just never sees its description, which means automatic invocation cannot fire. You are now running with a skill that is invisible to the very model that is supposed to choose it.
Why this happens at all
Skills are progressive disclosure. The agentskills.io spec puts the name + description block at "~100 tokens" per skill loaded at startup, with the full SKILL.md body only loading on activation. Stack twenty skills with verbose descriptions and you blow through the listing budget before the user has typed anything.
The 1024-character description cap in the agentskills spec is the hard maximum per field. The 1,536-character cap Claude Code applies is on the combined description + when_to_use text. Neither is a target. A skill description that hits 1,000 characters is doing the equivalent of taking up four parking spaces.
Codex has the same behavior with a slightly different shape. OpenAI's Codex reserves around 2% of the context window (or 8,000 characters when unknown) for the skills metadata list, and emits a Warning: Exceeded skills context budget of 2% when you go over. The percentage is currently hardcoded; there is an open issue asking for it to be configurable.
Three diagnostics, in order
1. Count your installed skills. Run /skills and count. If you are over fifteen, you are inside the danger zone on default settings. If you are over twenty-five, the tail is almost certainly truncated.
2. Measure description lengths. Open each SKILL.md and check the description field. Anything over 300 characters is a candidate for trimming. The model is choosing skills based on keyword density, not prose quality. A 900-character description does not get picked nine times as often as a 100-character one. It just eats the budget.
3. Check load order. Skills are ranked by usage frequency and recency for the drop decision. A skill you installed yesterday and have never invoked is the first thing to go. If a brand-new skill never fires, this is the likely culprit. Invoke it explicitly once, see if it fires the next session.
Three fixes
Tighten descriptions toward 100 to 200 characters with the trigger keywords front-loaded. The agentskills spec example, "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents," is 130 characters and does its job. The 1024 cap is a ceiling. Treat it like one.
Uninstall skills you do not actively use. The temptation with skills is to collect them like browser extensions. Every dormant skill steals listing budget from the ones you actually care about. If you have not invoked a skill in two weeks, delete the directory.
Use explicit invocation for the marginal ones. Skills you reach for occasionally do not need to be auto-discoverable. Set disable-model-invocation: true in the frontmatter and call them with /skill-name directly. They stop competing for the budget and still work when you want them.
If you have done all three and are still hitting the ceiling, raise the fraction in settings.json. Doubling it to 0.02 costs you about 2K extra tokens per session on a 200K window. That is cheap if it makes a skill you use daily reliable.
On writing descriptions that survive the cap
This is where most authors get it wrong. Treat the description as a routing signal for the matcher, not a pitch for the reader. The model is matching the user's request against your description and when_to_use fields, picking the closest match, and loading the body. Verbose context, brand voice, marketing language, none of it helps. Specific verbs and concrete nouns do.
Knack's interview-driven authoring flow writes descriptions in the 120-to-250-character band with the trigger keywords up front, because that is the shape that survives both the budget and the matching pass. If you are hand-writing SKILL.md files and watching them get dropped, the description is usually the first thing to fix.
A skill that never fires costs the same as no skill at all. Worse, actually, because you keep believing it is there.