Context Engineering: The Finite Attention Budget

This skill is an operating procedure for deciding what goes into an agent's context window — system prompt, tools, examples, memory, retrieved data, message history — and what stays out. It distills Anthropic's context-engineering guidance (2025) and its Claude 5-generation update (2026): treat every token as spending a finite attention budget, and prefer the smallest set of high-signal tokens over exhaustive instructions.

When to use

Use this skill when you are:

• Writing or auditing a system prompt, CLAUDE.md, agent skill, or tool set.
• Designing tools or an agent harness, especially with many tools or MCP servers.
• Debugging an agent that ignores instructions mid-run, loses recall on long contexts, or declares work done prematurely.
• Running long-horizon tasks (tens of minutes to hours: codebase migrations, research projects) where token count will exceed the context window.
• Migrating prompts written for older models to Claude 5-generation models (Claude Opus 5, Claude Fable 5).

Do NOT use for single-turn prompt tweaks where a short prompt already works — the standing guidance is "do the simplest thing that works." Do not apply the loosen-the-rules 2026 guidance blindly to older, less capable models; it was validated on Claude 5-generation models.

Rules

1. Treat context as a finite resource with diminishing marginal returns. Every token depletes the model's attention budget. Context rot is real: as tokens in the window increase, the model's ability to accurately recall information from that context decreases — driven by the transformer's n² pairwise token relationships. It is a performance gradient, not a hard cliff, so bloat degrades quietly. Optimize for "the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome" (Anthropic).
2. Prompt at the right altitude (the Goldilocks zone). Avoid both failure modes: over-specification (hardcoding complex, brittle if-then logic — fragile, high-maintenance) and under-specification (vague high-level guidance that assumes shared context the model doesn't have). Aim for instructions specific enough to guide behavior yet flexible enough to act as strong heuristics. Minimal does not mean short — include everything needed to fully outline expected behavior, and nothing else.
3. Give judgment, not rigid rules (2026 update). Replace prescriptive rules with judgment-enabling instructions. Example from Anthropic: instead of "never write multi-line comment blocks — one short line max," write "Write code that reads like the surrounding code: match its comment density, naming, and idiom." Rigid rules become wrong constraints in specific situations, and conflicting rules (e.g. "leave documentation as appropriate" alongside "DO NOT add comments") force the model to waste computation resolving contradictions instead of doing the task. Anthropic removed over 80% of Claude Code's system prompt for Claude Opus 5 and Claude Fable 5 with no measurable loss on coding evaluations.
4. Design expressive interfaces instead of piling on examples. Examples constrain the model to a certain exploration space. Where possible, encode expectations into the tool itself: expressive parameters, enumerations, and constraints that hint at correct usage. When you do use few-shot examples, curate a small set of diverse, canonical examples portraying expected behavior — never a laundry list of edge cases.
5. Build tools that are token-efficient and unambiguous. Tools must be self-contained, robust to error, and extremely clear about intended use; they should return token-efficient output and encourage efficient agent behavior. Apply the human-engineer test: if a human engineer can't definitively say which tool applies in a situation, the agent can't either. Prefer minimal tool sets — they make context easier to maintain and prune over long interactions.
6. Use progressive disclosure; load context just-in-time. Keep lightweight identifiers in context (file paths, stored queries, web links) and load full data at runtime via tools rather than pre-loading everything. Move detailed guidance into Skills the agent activates only when relevant; defer tool definitions and load them via ToolSearch only when needed. Exploit metadata as signal: folder hierarchy, naming, and timestamps carry meaning (a test_utils.py in tests/ implies something different from the same name in src/core_logic/). Hybrid is often best — Claude Code drops CLAUDE.md into context up front while glob and grep retrieve files just-in-time. Trade-off to respect: runtime exploration is slower than pre-computed retrieval, so pre-retrieve where content is stable (e.g. legal, finance).
7. Delete redundant instructions; keep one canonical location. Don't repeat guidance in both the system prompt and tool descriptions — consolidate into the tool description. In Claude Code, run /doctor to rightsize skills and CLAUDE.md files.
8. Keep CLAUDE.md lightweight and gotcha-focused. A brief repo description plus the non-obvious gotchas (e.g. where monolithic type files must live). Never state what the model can derive from the file structure itself. Push long verification procedures into progressively disclosed skills.
9. Prefer rich references over prose specs. A spec can be a detailed test suite, a function in a different codebase to port, an HTML mockup, or a rubric for a verifier agent. An HTML mockup of a design generally produces better results than a text description. Use @mention syntax to pull reference files into context.
10. Use memory instead of re-explaining. Claude 5-generation models auto-save relevant memories (auto-memory) — rely on that rather than manually curating CLAUDE.md via the # hotkey. For custom agents, use structured note-taking: persist notes outside the context window (a NOTES.md, a to-do list) and pull them back in later. The file-based memory tool on the Claude Developer Platform (public beta since Sonnet 4.5) lets agents build knowledge bases and maintain project state across sessions.
11. For long-horizon tasks, pick the right technique.

• Compaction — summarize a conversation nearing the window limit and reinitiate with the summary; best for tasks needing extensive conversational back-and-forth. Claude Code preserves architectural decisions, unresolved bugs, and implementation details, discards redundant tool outputs, and continues with the compressed context plus the five most recently accessed files. Tune by maximizing recall first, then iterate for precision. Cheapest win: clear old tool calls/results — "tool result clearing" is a feature on the Claude Developer Platform.
• Structured note-taking — best for iterative development with clear milestones.
• Sub-agents — best for research/analysis where parallel exploration pays; each sub-agent may burn tens of thousands of tokens exploring but returns only a condensed 1,000–2,000-token summary, keeping the lead agent's context clean for synthesis. Don't count on bigger windows: all sizes remain subject to context pollution where strongest performance is required.

12. Iterate empirically, not speculatively. Start with a minimal prompt on the best available model; add instructions and examples only against failure modes you actually observed in testing. Structure the prompt into distinct sections (e.g. <background_information>, <instructions>, ## Tool guidance, ## Output description) using XML tags or Markdown headers.

Checklist

System-prompt / context audit — run before shipping any agent prompt:

• Can I delete this line with no behavior change? Delete it. (Anthropic cut >80% of Claude Code's prompt with no eval loss.)
• Any rigid rule ("never X", "always exactly Y") that judgment-framing would replace? Rewrite as an outcome + heuristic.
• Any two instructions that contradict each other or a tool description? Resolve; keep one canonical copy (prefer the tool description).
• Is anything stated that the model can derive from file structure, code, or tool schemas? Remove it.
• Are examples a small, diverse, canonical set — not an edge-case laundry list? Could an enum/constraint in a tool parameter replace them?
• For each tool: would a human engineer know unambiguously when to use it? Are its outputs token-efficient?
• Is detailed guidance progressively disclosed (Skills, deferred tools via ToolSearch, just-in-time file reads) instead of front-loaded?
• Are specs rich references (test suite, mockup HTML, rubric, @mentioned code) rather than prose descriptions?
• Is CLAUDE.md a brief description plus gotchas only?
• Long-horizon plan chosen: compaction / note-taking / sub-agents — and old tool results cleared?
• Prompt organized into labeled sections; minimal starting version tested before additions?
• (Claude Code) /doctor run to rightsize skills and CLAUDE.md?

Anti-patterns

• Exhaustive rule lists. Hardcoded brittle logic that breaks on unanticipated cases and rots into contradictions the model must burn attention reconciling.
• Vague delegation. High-level guidance that falsely assumes shared context; no concrete signals for the desired output.
• Example hoarding. Stuffing every edge case into the prompt as few-shot examples — constrains exploration and spends the attention budget.
• Bloated tool sets. Overlapping tools with ambiguous decision points about which to use.
• Repeating yourself. The same instruction in system prompt and tool descriptions on the theory that repetition helps — it just doubles the cost.
• Pre-loading everything. Dumping full data objects into context up front instead of identifiers + just-in-time retrieval.
• Prose specs for visual/behavioral targets. A text description where a test suite, HTML mockup, or rubric would be a higher-fidelity reference.
• Overly aggressive compaction. Discarding subtle context whose importance only shows up later — tune recall first, precision second.
• Trusting a bigger window. Assuming a larger context window removes the need for curation; context pollution persists at every window size.

Source

• The new rules of context engineering for Claude 5 generation models — https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models — 2026-07-24
• Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents — 2025-09-29

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.