Coding Agent Token Budget: The 200K Token Skill That Taught Us a Lesson

In August 2026, Anthropic published a fix in the Claude Code changelog: the built-in /claude-api skill inlined its reference documentation straight into the prompt, burning roughly 120,000 tokens per invocation — and a one-line question could consume about 200,000 tokens before Claude started answering. After the fix, initial context cost dropped by at least 85.7%. As The New Stack reported, this is a lesson for every AI coding team: token budgets are not just a cost problem, they are a quality problem.

AI agents in the modern dev workflow

1. The Incident: How One Skill Ate 200K Tokens

Developers had already traced the problem before Anthropic documented the fix. In a GitHub issue opened July 7, a developer examining Claude Code 2.1.201 found that /claude-api embedded its shared reference files and the detected-language documentation directly into the skill body. The New Stack reports the invocation measured roughly 120,000 tokens of reference material; one migration document alone accounted for an estimated 36,000 tokens. Once the full skill loaded, even a one-line question could consume about 200,000 tokens before any answer.

# Before: a skill inlines EVERYTHING into the prompt
# One /claude-api invocation embedded ~120,000 tokens
# of reference material — a single migration doc was ~36,000 tokens
# A one-line question could burn 200,000 tokens before any answer

skill_bundle = {
    "name": "claude-api",
    "mode": "inline_all",          # bad: read all 812 KB
    "reference_files": [
        "migration-guide.md",      # 36,000 tokens alone
        "python-sdk.md",
        "typescript-sdk.md",
        # ... 26 shared markdown files
    ],
}

2. The Bigger Trap: Fallback When Language Detection Fails

A second bug report filed August 4 found an especially expensive fallback. When the skill could not detect a project language during a prompt audit, it loaded documentation for C#, cURL, Go, Java, PHP, Python, Ruby, and TypeScript, plus 26 shared Markdown files — a bundled directory of 812,650 bytes. Only one 32,954-byte file was needed up front for the task used in the reproduction. Inlining forced the agent to read all 812 KB on every request, even when most of it was irrelevant.

3. Why the Blank-Check Era Is Ending

Anthropic's own Claude Code best-practices guide warns that performance degrades as the window fills, with the model more likely to lose earlier instructions or make mistakes. The New Stack's verdict is blunt: the blank-check era of AI coding is ending precisely because unchecked token consumption degrades both quality and cost. A fuller context means worse answers and higher bills — a double hit.

# After: load reference documentation ON DEMAND
# Anthropic cut initial context cost by at least 85.7%
skill_bundle = {
    "name": "claude-api",
    "mode": "lazy_load",           # good: fetch only when needed
    "entry_points": [
        {"trigger": "import anthropic", "load": "python-sdk.md"},
        {"trigger": "import @anthropic-ai/sdk", "load": "typescript-sdk.md"},
    ],
    "fallback": "index.md",        # small file, not all 8 languages
}

4. The Fix: On-Demand and Lazy Loading

Anthropic's fix loads the skill's reference documentation on demand: only when a project actually imports the SDK does the agent load the matching language docs, instead of inlining everything up front. This pattern generalizes to any team: split skills and docs into entry points, load by trigger, and keep the default payload small. The goal is not zero documentation — it is that every line earns its place.

# Measure before you optimize: token audit script
# Hidden overhead only surfaces when you actually measure it
import tiktoken

def audit_skill_bundle(bundle_path):
    enc = tiktoken.encoding_for_model("claude-sonnet-4-5")
    total = 0
    for f in bundle_path.rglob("*.md"):
        tokens = len(enc.encode(f.read_text()))
        print(f"{f.name}: {tokens:,} tokens")
        total += tokens
    print(f"TOTAL: {total:,} tokens loaded per request")
    return total

# Real-world finding: 812,650 bytes bundled,
# only one 32,954-byte file was needed up front

5. Rolling It Out: Token Audits and CI Gates

Three actionable steps: first, write a token-audit script (e.g., with tiktoken) that counts what skill bundles and AGENTS.md actually consume; second, set a budget for inlined content — for instance 10,000 tokens per skill — and force lazy loading when exceeded; third, put the audit in CI so an oversized bundle fails the build. Hidden overhead only surfaces once someone actually measures it.

# CI gate: fail the build when a skill grows too fat
# Keep every line of agent docs earning its place
TOKEN_BUDGET = 10_000   # max tokens inlined per skill

def ci_check():
    total = audit_skill_bundle("skills/")
    if total > TOKEN_BUDGET:
        raise SystemExit(
            f"Skill bundle too large: {total:,} tokens "
            f"(budget {TOKEN_BUDGET:,}). Use lazy loading."
        )
    print("Skill bundle within budget ✅")

6. What This Means for Everyday Developers

This case is closer than it looks: every line of your AGENTS.md, CLAUDE.md, and custom skills gets re-read by the agent in every session. The more bloated the file, the higher the hidden cost per request. Audit your agent docs regularly with a token counter, delete stale content, and split big documents into small lazy-loaded files — you will save not only money but also the model's attention.