What you’ll be able to do
- Budget context per call: what must be present, what can be retrieved, and what should be summarized or dropped
- Manage token usage in long conversations and agent loops without losing critical facts
- Structure prompts so prompt caching engages, and verify it from usage data
- Choose between modular prompts, prompt caching and Skills for reusing instructions at scale
What you need to know
Context is a budget with three costs
Every token in a request costs money, adds latency, and competes for the model's attention. Large context windows make it possible to send a lot; they don't make it wise. Long, loosely relevant context can make the model less reliable at finding the one passage that matters, particularly when that passage sits deep in the middle of a long input. The architect's question for each call is: what does this step need?
- Always present: instructions, tool definitions, the output contract, and the facts the step can't work without.
- Retrieved on demand: reference material too large or too varied to send every time (policies, manuals, past tickets). Retrieval sends the relevant slices, and progressive discovery lets an agent fetch more when it needs it.
- Summarized or dropped: old conversation turns, superseded drafts, raw tool output that has already been acted on.
Put long documents before the question that refers to them, and label them clearly so the model (and you) can tell which is which.
Long conversations and agent loops
Token growth in production usually comes from two places: conversation history and tool results. An agent that calls a search tool ten times and keeps every full result in context can spend most of its budget on text it no longer needs.
- Trim tool results at the source. Have tools return the fields the agent uses, not the whole API payload. This is usually the single biggest saving in agent systems.
- Summarize with a schema. When history must be compacted, keep a structured "case facts" block (customer, amounts, dates, order numbers, decisions made, commitments given) and summarize the narrative around it. Free-text summaries tend to round off exactly the specifics that matter later.
- Isolate verbose work. Send exploratory or high-volume work to a subagent with its own context and return only the conclusion.
- Watch the output side. Output tokens are typically priced higher than input and dominate latency. Set sensible
max_tokens, ask for concise formats, and don't request reasoning where it isn't needed.
Measure before optimizing: the API reports input and output token usage per request, and a token-counting endpoint lets you size prompts before you send them.
Prompt caching: a placement problem first
Prompt caching lets the API reuse the processed form of a prompt prefix that repeats across requests, which reduces cost and latency on cached reads. It only works when the prefix is identical up to the cache breakpoint you mark with cache_control. So caching is mostly about ordering:
- Stable content first: tool definitions, system prompt, policies, few-shot examples, long reference documents shared across requests.
- Volatile content after the breakpoint: the user's message, retrieved passages specific to this request, timestamps, session IDs.
- Anything that changes per request and sits before the breakpoint (a "current time" line at the top, a user name in the first sentence, tools listed in a different order) means the prefix never matches and you pay to write the cache without ever reading it.
Verify it: the response's usage data reports tokens written to and read from the cache. A cache that's "enabled" but shows no reads is a prefix-stability bug. Cache lifetimes and pricing differ by option and change over time, so check the current documentation and match the choice to how often that prefix is actually reused. For work that isn't latency sensitive, the Message Batches API is a separate lever that trades turnaround time for lower cost.
Reuse at scale: modules, caching and Skills
Three mechanisms get confused because they all involve "reusing prompts":
- Modular prompts are a source-code practice: a base prompt composed with small, versioned modules (tenant, locale, task). They keep prompts maintainable and consistent; they don't by themselves reduce tokens sent.
- Prompt caching is a runtime optimization for a prefix you send repeatedly. It reduces the cost of what you send; it doesn't reduce how much you send or how much attention it takes.
- Skills package instructions, scripts and resources as a folder with a
SKILL.md. Only a short name and description sit in context up front; the full content loads when the task calls for it. That progressive disclosure is the point: an organization can hold dozens of procedures (brand guidelines, a filing workflow, a data-cleaning routine) without paying for all of them on every request, and reuse the same package across Claude surfaces such as Claude Code and the API.
A common Professional-level design uses all three: a modular, cached base prompt, with specialist procedures as Skills that load only when relevant.
Key concept
Send each step only the context it needs, keep the reusable prefix byte-identical so caching can engage, and move specialist instructions into modules or Skills that load on demand instead of riding along on every call.
When a stem mentions rising cost or latency with a large repeated prompt, look for prefix ordering and caching; when it mentions a long system prompt full of procedures most requests never use, look for Skills or retrieval; when quality drops as conversations grow, look at what's crowding the context.
Practice scenario
Work it through, then open this
Two problems. The per-request date and name at the very top change the prefix on every call, so the cache is written but never read; usage data will show cache writes and no reads. Move them after the breakpoint (or into the user turn) so the policy and tools form a stable prefix. Second, fourteen procedure guides ride along on every request though most requests need one or none. Package them as Skills (or retrieve them) so only the relevant procedure loads, which cuts tokens sent and reduces distraction. Then confirm in usage data that cache reads appear and input tokens per request fall.
Build exercise — Audit a prompt for token budget and cache stability
Advanced · 40 min
What you’ll learn
- Measuring where tokens go in a real request
- Reordering a prompt so the cacheable prefix is stable
- Deciding what to move into retrieval or Skills
-
Take a production-style request and break its input tokens down by section (tools, system prompt, examples, reference docs, history, tool results, user input), using the usage data or the token-counting endpoint.
- Why: You can’t budget what you haven’t measured; tool results and history are often bigger than expected.
- You should see: One or two sections accounting for most of the input, and at least one that most requests don’t need.
-
Reorder the prompt so everything stable comes first, add a cache breakpoint after it, and move every per-request value after the breakpoint. Send a few identical-prefix requests.
- Why: Caching only engages on an identical prefix.
- You should see: Cache write tokens on the first request and cache read tokens on the following ones.
-
For each section most requests don’t use, decide whether it becomes retrieved content, a Skill, or is deleted, and write down the rule that decides when it loads.
- Why: Progressive disclosure keeps specialist knowledge available without charging every request for it.
- You should see: A smaller always-present prefix and a short list of on-demand modules with clear triggers.
Exam traps
Filling the context window because the model can accept it
More context costs money and latency and can make the relevant passage harder to use. Send what the step needs.
Putting timestamps, user IDs or other per-request values at the top of the prompt
They change the prefix on every call and defeat caching. Keep volatile values after the cache breakpoint.
Summarizing long conversations in a way that drops amounts, dates and commitments
Keep a structured block of case facts and summarize around it, so the specifics survive compaction.
Assuming caching is working without checking cache read tokens in usage data
Enabled is not engaged. Usage data shows whether reads are happening.
Loading every playbook into the system prompt instead of loading it when relevant
Use Skills or retrieval so specialist content loads only when a task needs it.
Ignoring output tokens and verbose tool results when reducing token cost
Output is often the costlier and slower side, and raw tool payloads bloat agent context. Trim both.
Sources
- Claude Developer Platform Docs: context windows, prompt caching, token counting, Message Batches
- Claude Developer Platform Docs: Agent Skills
- Anthropic: Equipping agents for the real world with Agent Skills
- Anthropic, Claude Certified Architect – Professional Exam Guide v1.0 (July 2026)