A Claude Code skill designed to help developers work with Anthropic’s API was found consuming roughly 200,000 tokens simply by loading its documentation. The issue exposed a major problem with how large AI skills can consume context, and Anthropic’s skill architecture is now moving toward a more selective, on-demand approach.
The problem is especially important for developers using AI coding agents because tokens are not just about generating answers. Large amounts of documentation, tool definitions and skill instructions can also occupy the model’s context window.
In one reported case, the claude-api skill loaded around 210,000 tokens of documentation after a simple question about Claude models.
That meant a developer could lose a huge portion of the available context before Claude had even started doing meaningful work.
What Happened?
Claude Code supports Skills—specialized instruction packages that give Claude additional knowledge and workflows.
The idea is useful.
Instead of putting every possible instruction into Claude’s main system prompt, a skill can contain detailed information about a specific task.
For example, the claude-api skill contains information about:
- Anthropic’s API
- SDKs
- Model selection
- Tool use
- Prompt caching
- Agents
- Streaming
- Structured outputs
- Different programming languages
- Model migration
The problem appeared when Claude Code loaded too much of that information at once.
A reported issue showed that a 570 KB SKILL.md payload represented roughly 210,000 tokens and was injected into the conversation as a single block.
Another report found a similar problem where a claude-api skill invocation added approximately 227,000 tokens to a session.
A Simple Question Could Trigger a Huge Documentation Load
The surprising part was that users did not necessarily need to ask for complicated API development.
One reported example involved a relatively simple question about Claude model usage.
Because the prompt mentioned Claude models, the skill could be triggered and load a huge amount of documentation.
The result was extremely inefficient:
Small question → Skill triggered → Huge documentation loaded → Context consumed → Answer generated
Instead of:
Small question → Relevant information loaded → Answer generated
This distinction matters enormously for AI coding agents.
Why 200,000 Tokens Is a Big Deal
Tokens are the basic units AI models use to process text.
A token can represent part of a word, a complete word or punctuation.
When an AI system has a 200,000-token context window, that space includes much more than the user’s message.
It can contain:
- System instructions
- Previous conversation
- Tool definitions
- Skill instructions
- Source-code files
- Tool results
- Documentation
- AI-generated reasoning
So if a skill consumes around 200,000 tokens, it can effectively fill the entire context window before the actual task gets underway.
One reported test showed that a simple question caused the session context to jump from around 45,000 tokens to roughly 256,000 tokens after the skill loaded.
For users on a 200K context model, that could result in a context-limit error.
The Bigger Problem: Context Is Becoming Infrastructure
This incident highlights an important change in AI development.
As AI agents become more capable, context management is becoming almost as important as model intelligence.
An AI coding agent may need access to:
Code + documentation + tools + memory + instructions + previous work
But putting all of that into the context at once is inefficient.
The model needs a way to find the information it needs without carrying everything all the time.
That’s where progressive disclosure comes in.
What Is Progressive Disclosure?
Progressive disclosure means an AI system starts with a small amount of information and loads additional details only when they are needed.
Think of it like this:
Old approach
Load everything
API documentation
Python documentation
Java documentation
Go documentation
Tool-use documentation
Agent documentation
Migration guides
Pricing information
Model information
etc.
Better approach
Load only what the task requires
User asks about Python API → load Python API documentation.
User asks about tool use → load tool-use documentation.
User asks about model migration → load migration documentation.
This can dramatically reduce context usage.
Anthropic’s own documentation describes Skills as something Claude should load when relevant, with the skill description available by default and detailed information loaded when the task requires it.
Anthropic’s Skill Architecture Already Points Toward This
Interestingly, the source version of Anthropic’s claude-api skill is much more structured.
The current public SKILL.md tells Claude to select the appropriate documentation and then read the relevant language-specific or task-specific files.
The skill includes separate references for areas such as:
- Tool use
- Agent design
- Model migration
- Language-specific APIs
- Managed Agents
- Prompt caching
That is much closer to a load-what-you-need architecture.
The problem was that some Claude Code bundled versions were reported to inline large portions of those resources when the skill was invoked.
One report specifically described the bundled packaging as defeating the intended progressive-disclosure model by pre-rendering reference files into the skill payload.
The 87% Figure Needs Context
The 87% reduction figure circulating online should be treated carefully.
It does not appear to mean that Anthropic officially announced:
“We reduced the Claude Code skill from 200K tokens to 26K tokens.”
Instead, 87% figures have appeared in discussions and projects around token-efficient skill design and related Claude Code workflows.
For example, one open-source Claude Code skill collection reports an approximately 87% reduction during skill discovery by using progressive loading rather than loading complete documentation.
Other community reports have also described Claude Code skills achieving up to 87% reductions in specific tasks through more concise output or better skill design.
So the safest interpretation is:
The 87% figure represents the kind of reduction achievable through better context and skill management, rather than a confirmed single Anthropic-wide reduction of this exact claude-api incident.
That distinction is important.
Anthropic’s Public Skill Is Becoming More Selective
The current public claude-api skill has a much narrower trigger description than simply responding to every mention of Claude.
It says the skill should trigger for things such as:
- Anthropic SDK code
- Claude API requests
- Managed Agents
- Claude-specific feature changes
- Prompt caching questions in an Anthropic SDK project
It also explicitly says to skip unrelated provider-neutral programming and projects using other AI SDKs.
That is an important architectural improvement.
The AI should first determine:
“Does this task actually require this skill?”
rather than:
“Did the user mention Claude?”
Why This Matters for AI Coding Agents
This problem isn’t unique to Claude Code.
Every AI coding agent faces the same challenge.
Tools such as AI coding assistants increasingly have access to:
- Hundreds of tools
- Large documentation libraries
- Project files
- Git history
- Skills
- MCP servers
- External APIs
- Memory
- Long conversations
If everything is loaded into context, the AI becomes expensive and less efficient.
This creates a new engineering principle:
Don’t give the AI everything. Give it the right information at the right time.
More Context Doesn’t Always Mean Better AI
There is a common assumption that a larger context window automatically makes an AI agent better.
That’s not always true.
A huge context can create several problems.
Higher cost
More input tokens can increase usage.
The model has more information to process.
Slower processing
Less useful context
Important information can become buried among irrelevant material.
Context exhaustion
The model may run out of usable context before completing the task.
Repeated overhead
Large instructions can remain part of subsequent requests in a long-running session.
This is why efficient context management is becoming a major part of AI-agent engineering.
The Future: AI Agents That Load Knowledge Dynamically
The long-term solution is likely to look more like a search engine than a giant instruction manual.
Instead of giving an AI agent a 200,000-token document, the system can give it:
A small index → relevant section → specific example → answer
For example:
A developer asks:
“How do I enable prompt caching in the Python SDK?”
The ideal agent doesn’t need the entire Anthropic API documentation.
It needs:
Python → Prompt caching → Current API example
That’s it.
This Could Save Millions of Tokens
At a larger scale, the savings become significant.
Imagine an organization with:
- 1,000 developers
- 100 AI-agent interactions per developer per day
- Large skills and documentation loaded repeatedly
Even a few thousand unnecessary tokens per interaction can become a huge amount of compute.
Reducing context size can therefore improve:
Cost + speed + reliability + scalability
For companies running AI agents at scale, these savings could become substantial.
Developers Are Starting to Treat Skills Like Software
Another interesting development is that developers are beginning to engineer their AI skills more carefully.
Instead of writing one enormous SKILL.md, developers are splitting information into:
Router → References → Examples → Tools
The router determines what the agent needs.
The references contain detailed knowledge.
The agent only loads the relevant pieces.
Anthropic’s own skill-development guidance emphasizes modular skills and bundled resources, while the Claude API skill itself points to separate language and topic-specific reference files.
What Developers Should Learn From This
If you’re building Claude Code skills or AI-agent workflows, the lesson is simple.
Keep the entry point small
Don’t put hundreds of pages of documentation into the main skill.
Use clear triggers
A skill should activate only when the task actually needs it.
Split large documentation
Separate API references, examples and advanced topics.
Load information on demand
Use targeted reads instead of loading everything.
Monitor token usage
Check where your context is being consumed.
Avoid unnecessary tool schemas
Large tool collections can also create context overhead.
This is becoming especially important as AI agents gain access to more tools.
The Bigger Picture
The Claude Code skill incident may look like a relatively small developer-tool problem.
It isn’t.
It highlights one of the biggest challenges facing the next generation of AI agents:
Context management.
AI models are becoming more powerful, but giving them more information isn’t automatically the answer.
The real challenge is deciding which information they need, when they need it and how much of it should enter the context.
The reported 200K-token skill load showed what happens when that process goes wrong.
The move toward progressive disclosure and more selective skill triggering points toward a better approach.
Instead of building AI agents that know everything all the time, developers are moving toward agents that can find what they need when they need it.
And that could become one of the most important optimizations in AI development.
The future of AI agents may not depend on giving models bigger memories alone. It may depend on teaching them how to use those memories efficiently.
By
