Context Budget Skill for Claude

Context budget

The context window is RAM, not a hard drive. Full ≠ free: a window stuffed to 95% does not just cost more money, it *reasons worse*. Model performance degrades as input tokens grow — even well inside the stated limit, every token added depletes a finite attention budget (Chroma "Context Rot" research, accessed 2026-06-02). Your job on a long task is to keep the *live* window lean and externalise everything else, so the work can run for hours across many fresh windows without losing the thread.

> The one rule: if you can reconstruct a thing from a file or from git, it does not belong resident in the window. Keep load-bearing-right-now; evict the rest. The cost of forgetting is one re-read; the cost of hoarding is silent quality rot on every turn that follows.

Neighbours, so you don't do their job here: pricing tokens, spend ledgers and hard $ caps are ../cost-tracking/SKILL.md — same words ("token budget"), different unit, dollars vs. attention. Finding the *right* context via embeddings/chunking is ../rag/SKILL.md; RAG is *how you find* context, this is *how much* you let live and *when to evict*. Prompt text, few-shot and output format are ../prompt-engineering/SKILL.md; the agent loop, tool schemas and provider adapters are ../building-agents/SKILL.md; partition-then-gather fan-out of independent work is ../parallel/SKILL.md (this skill *uses* subagents as a context-isolation tactic but does not own that discipline); the 01-TOOLS / 02-DOCS control plane is ../harness/SKILL.md.

Read the gauge first

Before you do anything, estimate utilisation: live input tokens ÷ the model's window limit. You cannot manage a budget you are not watching.

• Compact early — around ~60% utilisation, not 80–95%. Most people only act when quality already broke at 80–95%; by then the rot already happened. Treat 60% as the line where you start reducing, not panicking (practitioner guidance on Claude Code /compact, accessed 2026-06-02).
• Trust the symptoms as an *earlier* trigger than the number. You can feel rot before the gauge confirms it:
• You re-read a file you already read this session.
• You restate the plan or a decision you already made.
• You contradict an earlier choice.
• Tool results from ten turns ago are still sitting verbatim in the window.

Any one of those is a signal to act now, regardless of the percentage.

The four moves

Every context-engineering action is one of four moves (context-engineering surveys, accessed 2026-06-02). Pick by *what is eating the window*.

1. Offload — summarise a tool output or large read; store the full thing in a file or reference, keep only the distilled fact + a path. *Why: raw bytes you might need later don't have to be resident now.*

Bad:  <pastes the entire 4,000-line config file into the window to "have it">
Good: read it, keep the 30 relevant lines, leave a note:
      "full config at src/app/config.ts:1-4012; the load-bearing keys are X, Y, Z (lines 88-120)"

2. Reduce — compact or summarise stale history so the window carries the *conclusions*, not the journey. *Why: the dead-end exploration that got you to a decision is not the decision.*

Bad:  carry 2,000 lines of trial-and-error debugging transcript forward unchanged.
Good: compact to "tried A (failed: race condition), B (failed: types); C works — see commit a1b2c3d."

3. Retrieve — fetch a fact at runtime instead of pre-loading it. *Why: most of what you might need, you won't; pull it when you actually need it.* This is RAG's job — see ../rag/SKILL.md.

Bad:  load all 40 design-doc sections up front in case one is relevant.
Good: keep an index; fetch section 7 the moment the task touches auth.

4. Isolate — hand a read-heavy or independent subtask to a subagent with its own fresh window; take back only the answer. *Why: a big read in a child window never pollutes the parent's.* Subagents are the single most effective anti-rot pattern (Anthropic context-engineering guidance, accessed 2026-06-02).

Bad:  read 12 files into the main window to answer "which module owns retries?"
Good: spawn a subagent to scan them; it returns "retries live in lib/http/retry.ts:44" — that one line lands in the parent.

Decision table: the window is filling — what do I do?

| What is eating the window | Move | Concrete action |

|---|---|---|

| Bloated tool output / a giant pasted file or log | Offload | Distil to the load-bearing lines, write the full thing to a file, keep a path:line note. |

| Stale early history, dead-end exploration | Reduce | /compact now (you're at ~60%, not 95%) with preserve instructions; keep decisions, drop the journey. |

| A fact you need is simply not in the window | Retrieve | Fetch it on demand via ../rag/SKILL.md; don't pre-load "just in case". |

| A read-heavy or independent subtask | Isolate | Spawn a subagent (fresh window) via ../parallel/SKILL.md; take back only the answer, never the transcript. |

| The whole task won't fit any single window | Hand off | Write a progress file (below) so a fresh window resumes in one read. |

Compaction, concretely

Manual (/compact). Do it early and tell it what to keep. A bare /compact will happily drop the file paths and decisions you needed.

/compact keep: the migration plan, every file path touched, the three decisions
(use Drizzle, keep the legacy table read-only, cut over Friday), and the open TODOs.
drop: the exploratory diffs and the debugging transcript.

Server-side (beta). The API can compact for you: beta header compact-2026-01-12, edit type compact_20260112, default trigger at input_tokens = 150,000 (min 50,000), pause_after_compaction defaults false. The API drops all blocks before the compaction block and continues from the <summary> — and you must append the *whole* response (including the compaction block) to subsequent requests (Claude API "Compaction" docs, accessed 2026-06-02). The exact contract and the append rule are version-specific and rot fastest, so they live in references/handoff-and-compaction.md — read it before you wire this up.

A good summary preserves decisions, file paths, open TODOs, and gotchas/constraints. A good summary drops raw logs, dead-end exploration, and redundant restatements. If the summary can't resume the task, it failed.

Surviving a fresh window (handoff discipline)

When the task is bigger than one window, the win is making a *fresh* window resume the work in a single read. The long-running harness pattern (Anthropic, "Effective harnesses for long-running agents", published 2025-11-26, accessed 2026-06-02) is: an initializer session sets up the work, then each coding session works one unit at a time and leaves a structured update — a progress log (e.g. claude-progress.txt) plus git history plus a structured feature list — so the next window reconstructs state without you re-explaining it.

Write the handoff *before* you run out of room, not after quality already cratered. The template (Goal / Done / In-progress / Next / Gotchas / Key paths) and a good-vs-bad summary checklist are in references/handoff-and-compaction.md.

Budget allocation heuristic

A starting split for a production agent's window — a heuristic, not a law (context-engineering production guidance, accessed 2026-06-02). Tune to your task; the point is to leave headroom and trigger reduction well before 100%.

| Slice | Rough share |

|---|---|

| System / instructions | ~10–15% |

| Tool definitions & results | ~15–20% |

| Knowledge / RAG injections | ~30–40% |

| Working headroom (kept clear) | the rest — defend it |

Anti-patterns

| Anti-pattern | Why it rots | Do instead |

|---|---|---|

| Read the whole repo into context "to be safe" | Thousands of irrelevant tokens degrade every later turn | Read the files the task touches; leave path notes for the rest |

| Compact only at 95% when things break | The rot already happened; you're summarising damaged reasoning | Compact at ~60%, before quality drops |

| Let tool results pile up verbatim | Stale outputs from 10 turns ago still taxing attention | Offload to a file, keep the distilled fact + path |

| Re-explain the plan every turn | Burns the same tokens repeatedly and invites drift | State it once; keep it in the progress file, reference it |

| Paste a subagent's full transcript back into the parent | Defeats the entire point of isolation — the child's bloat lands in the parent | Take back only the answer/artifact, never the transcript |

| Treat the window as infinite because the model "has 1M" | Context rot scales with tokens regardless of the limit | Budget against attention, not the advertised ceiling |

| Carry dead-end exploration forward | The journey isn't the decision; it's pure noise | Reduce to the conclusion + the commit that proves it |