Curriculum › Claude Models, Prompting & Context Engineering · 13% of the exam

Context windows, token usage and prompt reuse

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

ScenarioA legal-operations assistant sends, on every request, a system prompt that begins with "Today is {date}, user {name}", followed by a long matter-management policy, then fourteen procedure guides (NDA review, subpoena intake, litigation hold and so on), then the user's question. Prompt caching was enabled last month, but costs didn't move. Most requests use one procedure or none.
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
  1. 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.
  2. 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.
  3. 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

Quick check

A benefits-eligibility step applies six interacting conditions, and errors cluster on cases where several conditions apply at once. The team added an instruction to think step by step, and accuracy improved, but the downstream system now fails to parse the decision because it is buried in prose. What is the best fix?