A Claude Code skill was eating 200,000 tokens before answering a single question

Turns out one of Claude Code's own built-in tools was quietly torching your context window before you'd typed a real question. The /claude-api skill, meant to help developers working with Anthropic's API and Managed Agents, loaded all of its reference documentation upfront every single time it fired. A GitHub issue from July 7 caught it in the act on Claude Code 2.1.201: roughly 120,000 tokens of reference material stuffed into one invocation, with a single migration document alone accounting for an estimated 36,000 tokens. Add in the rest of the skill's payload, and a one-line question could rack up around 200,000 tokens before Claude said a word.

That first report got closed as a duplicate and marked not planned, which is a little awkward given a second bug report on August 4 found something even messier. When the skill failed to detect which language a project was using, it just loaded documentation for everything — C#, cURL, Go, Java, PHP, Python, Ruby, TypeScript — plus 26 shared Markdown files, totaling 812,650 bytes. The task in question actually needed one 32,954-byte file. Everything else was dead weight, read in full on every request regardless of relevance.

With Claude Code v2.1.234, Anthropic says it has trimmed the skill's footprint to roughly 25,000 tokens, an initial-load reduction of at least 85.7%, by switching to on-demand loading of the reference material instead of dumping it all in at once. Anthropic's own skill-authoring guidance actually spells out how this is supposed to work: SKILL.md should carry the core instructions and links, while the heavier specs and examples sit in supporting files that only get opened when Claude actually needs them. The old /claude-api behavior collapsed that distinction, treating bundled resources like they belonged in the always-loaded body.

The company hasn't detailed exactly how Claude now decides which documents to pull in, only that it does so as needed rather than eagerly. That leaves a bit of uncertainty, and possibly an extra file read once Claude figures out which language or API feature actually matters. But that's a far cheaper trade than reading 812 KB of mostly irrelevant docs for every prompt.

What makes this notable is how invisible the whole problem was. Claude Code's documentation already warns that a skill's body stays resident in context across turns, even though a developer only sees the small request and response on screen. Anthropic's best-practices guide separately notes that performance degrades as the context window fills — the model starts losing earlier instructions and making more mistakes. So a bloated built-in skill wasn't just an inefficiency sitting quietly in the background; it was actively working against the quality of every session that triggered it, for however long the fix took to land.