What you will be able to do
- Order a repeated prompt so that content changing least often comes first, then place up to four breakpoints on the last stable block of each layer
- Explain why requests launched at the same moment all write the cache, and choose a launch or pre-warm pattern that turns them into reads
- Identify which request changes invalidate the tools, system or messages cache, and move per-request variation behind the last breakpoint
- Package reusable guidance as Skills or deferred tools so it loads on demand without changing the cached prefix
Key concept
Cached prefix — A cache hit reuses the exact run of tokens from the start of the request (tools, then system, then messages) up to a block marked with cache_control. Anything that changes earlier in that run produces a different prefix and a cache miss.
1.How a cached prefix is matched
Prompt caching lets a request skip reprocessing the part of the prompt an earlier request already sent. It pays off when the same large block of text goes out again and again: a policy manual sent with every question, a tool catalogue sent with every agent step, a long conversation resent on each turn. Each of these is a repeated call pattern, and the work of caching is arranging that pattern so the repeated part sits in front and stays identical byte for byte.
The order of matching is fixed. The API builds the prefix from tools first, then the system prompt, then messages, and it only matches when every token up to the breakpoint is the same as before. A single changed character anywhere earlier, such as a timestamp or a reordered field, gives a different prefix. That means you control reuse through ordering: static material such as tool definitions, system instructions, background context and examples goes at the start, and the cache_control marker goes where that material ends.
There are two ways to mark the prefix. With automatic caching you set one top-level cache_control, and the API puts the breakpoint on the last cacheable block, moving it forward as a conversation grows. With explicit breakpoints you put cache_control on particular content blocks. The two can be combined: in the request below, an explicit marker caches the system prompt and the top-level marker handles the conversation. The automatic breakpoint takes one of the four available slots.
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}Lookback cannot rescue a badly placed breakpoint. An entry is written only at a breakpoint. If the marker sits on a block that changes on every request, like the incoming user message, every request writes a new entry under a new hash. The lookback window does not walk back to find the stable text in front of that block. It only finds entries that earlier requests wrote at their own breakpoints. So the rule is to put the breakpoint on the last block that stays identical across requests, which is the end of the static prefix, not the varying block after it.
Three response fields show whether this is working. cache_creation_input_tokens counts tokens written to the cache, cache_read_input_tokens counts tokens served from it, and input_tokens counts tokens after the last breakpoint that were neither written nor read. A prefix that should be shared but keeps showing up as creation tokens is being rebuilt on every call. Writes cost more than plain input (25 percent more for the 5-minute TTL) and reads cost much less. The full rates are covered in token economics.
Checkpoint 1 of 9· Fill the gap
This request caches the system prompt with an explicit breakpoint and lets automatic caching handle the growing conversation. Which top-level field turns on the automatic part?
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
" ? ": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}Automatic caching uses the same cache_control field as explicit breakpoints, but placed at the top level of the request. The API then puts the breakpoint on the last cacheable block, and that automatic breakpoint takes one of the four slots.
Source: platform.claude.comCheckpoint 2 of 9· Check yourself
A support bot sends the same 20k-token policy manual as its system prompt on every call, followed by the customer's question with a timestamp. The developer puts the only explicit cache_control on the user message and expects a cache hit on the manual. What happens, and what is the fix?
Entries are written only at a breakpoint, and lookback finds only entries that earlier requests wrote at their own breakpoints. A marker on a block that changes every time never matches. The marker belongs on the last block that stays identical across requests.
“Place the breakpoint on the last block that stays identical across requests.”Source: platform.claude.com
Sources1
2.Cache writes land when a response starts
On a miss, the system processes the full prompt and stores the prefix once the response begins. Requests launched at the same instant are all checked before any entry exists, so each one is a miss and each one pays the write price. A perfectly ordered prompt can still be billed almost entirely as writes because of how the requests are launched.
The fix is about timing. Send one request first and start the rest once its response is streaming. They will then find the stored prefix and read it. None of the obvious alternatives helps:
- A 1-hour TTL changes how long an entry lives, not when it is written, so a simultaneous launch still finds nothing.
- Shuffling the submission order still launches everything together.
- Adding a breakpoint after each unique question writes entries that no other request shares.
Pre-warming does the same thing without spending a real query. Set max_tokens: 0, and the API reads the prompt, writes the cache at each breakpoint, and returns an empty response. Put the marker on the last block the real requests share, usually the system prompt or tool definitions, not on the placeholder user message. If the marker is on the placeholder, the entry is keyed to that placeholder and real traffic never hits it. For the same reason, pre-warming needs an explicit breakpoint, because automatic caching would choose the placeholder. Claude Code applies the same idea to workflow fan-outs: it holds back every agent after the first for up to five seconds so the others can read the prefix the first one cached.
Checkpoint 3 of 9· Check yourself
Before opening a chat feature, a team pre-warms the cache. They send max_tokens: 0, a top-level cache_control (automatic caching), their 30k-token system prompt and a placeholder user message "warmup". Real requests come in less than a minute later with the same system prompt, but they still show the system prompt as cache_creation_input_tokens. Why, and what is the fix?
Automatic caching puts the breakpoint on the last block. In a pre-warm request that block is the placeholder, so the entry never matches real traffic. An explicit breakpoint on the last shared block, such as the system prompt, writes an entry that the real requests can read.
“automatic caching places the breakpoint on the last block, which here is the placeholder.”Source: platform.claude.com
Checkpoint 4 of 9· Exam question
A nightly job on the Messages API fans out 200 parallel requests, each with a different question but all sharing the same 60,000-token policy prefix that ends in a cache_control breakpoint. The job launches all 200 at the same instant, and nearly every request is billed as a cache write. Which launch pattern fixes this?
Correct answer: A — Send one request ahead of the rest and start the other 199 once its response begins streaming, so they find the stored prefix.
- A. Correct: a cache entry can be read only after the request that wrote it has begun its response. Letting one request establish the prefix first means the remaining 199 calls read it at the cheaper cache-read rate instead of each paying for a write.
- B. Incorrect: the TTL sets how long an entry survives once it exists, not when it becomes readable. With 200 requests launched at the same instant, none has begun responding, so none finds an entry, whatever the lifetime.
- C. Incorrect: each request carries a different question, so a breakpoint after it produces a prefix that no other request matches. It adds write cost and does nothing for the shared 60,000-token prefix that is being rewritten.
- D. Incorrect: because all requests are in flight together, no request has begun responding when the others arrive, so none can read what another is still writing. Reordering only changes which request writes, not how many pay for a write.
3.Layering content by change frequency
Most real prompts aren't simply static or dynamic. They have layers that change at different rates, and explicit breakpoints exist for that case: they let you cache sections with different change frequencies separately. Order the layers from slowest-changing to fastest, and place a breakpoint on the last block of each layer that you want to survive when the next layer changes. A request can carry at most four breakpoints. Extra breakpoints add no cost, because billing depends only on what is actually written and read.
| Layer | Changes | Breakpoint | What it protects |
|---|---|---|---|
| Tool definitions and system instructions | Every few months | On the last system block | The tools-and-system entry still hits after the digest below it is regenerated |
| 20,000-token pricing digest | Once a day | Optional, at the end of the digest | Lets sessions across the day share the digest |
| Customer account summary | Once per session | On the final block of the summary | Turns 2 to 15 of a session read everything through the summary |
| Running conversation | Every turn | Automatic caching, or none | The growing history |
Getting the order wrong ties a slow layer to a fast one. If the per-session account summary is moved ahead of the daily digest, the digest's cached entry now includes one customer's summary, so a new entry is written for every session instead of once a day. If today's date is added as the first system block, a value that changes daily now sits in front of tools and instructions that would otherwise stay cached for months. A short date line is also below the minimum cacheable length, which is 512 tokens on current models such as Claude Opus 5.5 and Sonnet 5.5.
Mixing TTLs follows its own ordering rule. A 1-hour entry must come before any 5-minute entry, so a 5-minute breakpoint on the system prompt followed by a 1-hour breakpoint on the digest is not a valid layout. Choose TTL from how often a prefix is reused. A prompt sent more often than every five minutes should stay on the default 5-minute TTL, which refreshes for free each time it is read. The 1-hour TTL, which costs 2x base input to write, is for prefixes reused at intervals between five minutes and an hour, such as a user who may take a while to reply.
Yes. That is three explicit breakpoints plus the automatic one, which uses the fourth of the four slots. A fifth would not fit, and if four explicit breakpoints already exist, adding automatic caching returns a 400 error.
Checkpoint 5 of 9· Check yourself
The billing assistant's team wants the daily pricing digest to stay cached for an hour, because sessions arrive spread out across the day. They leave the system-prompt breakpoint on the default 5-minute TTL and add a breakpoint with "ttl": "1h" at the end of the digest, which comes after the system prompt. What is wrong with this layout, and what fixes it?
When TTLs are mixed, longer TTLs must appear earlier in the prompt, so a 5-minute breakpoint cannot come before a 1-hour one. Moving the daily digest ahead of the instructions is the wrong fix: it puts a layer that changes daily in front of instructions that would otherwise stay cached for months.
“a 1-hour cache entry must appear before any 5-minute cache entries”Source: platform.claude.com
Checkpoint 6 of 9· Exam question
A billing assistant on the Messages API builds each request from: tool definitions and system instructions (unchanged for months), a 20,000-token pricing digest (regenerated once a day), a customer account summary (fixed within a session), then the running conversation. Sessions run 5 to 15 turns. Which two breakpoint placements maximize reuse across this call pattern? Choose two.(Select 2)
Correct answers: A, B — Place a breakpoint on the last system block, so the tools and system entry survives when the digest is regenerated.; Place a breakpoint on the final block of the account summary, so later turns in a session read the prefix up to that block from cache.
- A. Correct: a marker after the long-lived system content writes an entry for tools and system alone. When the digest is regenerated each day, only the later segment is rewritten and the earlier entry stays valid.
- B. Correct: the account summary is fixed within a session, so a marker at its end writes the prefix once. Later turns in that session read tools, system, digest and summary from cache and pay only for the new conversation turns.
- C. Incorrect: placing per-session content ahead of the digest gives each customer a different prefix, so the digest cannot be reused across sessions. Content that changes more often has to come later in the prompt.
- D. Incorrect: a date that changes daily sits at the start of the system content, so the system entry and everything after it are invalidated each day. That throws away the months-long stability of the system prefix.
- E. Incorrect: when lifetimes are mixed, entries with the 1-hour TTL must come before those with the 5-minute TTL. Here the 5-minute marker precedes the 1-hour one, which breaks that ordering rule, and a longer lifetime on the digest would not help once the daily digest change invalidates the prefix.
Sources1
4.Changes that break the prefix
The tools → system → messages hierarchy also determines how much a change costs you: a change at one level invalidates that level and everything after it. Tools come first, so any change to the tool list, including which tools are sent and in what order, invalidates the whole cache. A system-prompt change keeps the tools entry and loses everything after it.
| Change | Invalidates |
|---|---|
| Modifying tool definitions | Entire cache (tools, system, messages) |
| Toggling web search or citations | System and messages caches |
| Changing tool_choice | Messages cache |
| Toggling images present/absent | Messages cache |
| Changing thinking parameters | Messages cache always; tool and system caches too on some models |
| Changing output_config.effort | Can invalidate the messages cache, and on some models tool and system caches too |
Take a support-triage agent that saves tokens by sending only the 4 to 9 tools relevant to each ticket category, in varying order, and puts a persona note for the customer's tier at the top of the system prompt. Both choices put request-specific content at the very front, so cache reads become rare. The fix is to send all 14 tool definitions every time, in one fixed order, and state the ticket category in the final user message. Then move the tier note out of the system prompt into the user message after the last breakpoint. Sorting a filtered list alphabetically does not help, because the subset still changes. Breakpoints for each subset only create separate prefixes that never match each other. A longer TTL just keeps a non-matching entry alive for longer.
Less visible sources of variation break the cache the same way:
- Languages such as Swift and Go can randomize JSON key order, so the keys in tool_use blocks may serialize differently on each call.
- tool_choice, image usage, the thinking configuration and output_config.effort must stay the same between calls.
- A model switch: in Claude Code, each model has its own cache, so switching recomputes the entire request.
Checkpoint 7 of 9· Match them up
Match each change between two otherwise identical requests to the part of the prompt cache it invalidates.
Tap a term, then the definition that fits it.
The cache follows the tools → system → messages order, so a change invalidates its own level and everything after it. Tool definitions come first, so changing them clears everything. Web search affects system and messages, and tool_choice affects only messages. Thinking parameters always invalidate messages, and on some models they also invalidate tools and system.
“The cache follows a prefix hierarchy (tools → system → messages), so a change at one level invalidates that level and everything after it”Source: platform.claude.com
Checkpoint 8 of 9· Exam question
A support-triage agent on the Messages API sends 14 tool definitions, a 6,000-token system prompt and then the ticket. To save tokens, the team currently sends 4 to 9 tools in varying order depending on the ticket category, and it prepends a persona note for the customer's tier at the top of the system prompt. Cache reads are rare. Which two changes restore reuse? Choose two.(Select 2)
Correct answers: A, B — Send the full set of 14 tool definitions in one fixed order, and name the ticket category in the final user message.; Move the tier persona note out of the system prompt, and place it in the user message that follows the last breakpoint.
- A. Correct: the cache prefix is built in the order tools, system, messages, and a change to the tool definitions invalidates what follows. One fixed set of 14 keeps the first segment byte-identical across tickets, and the category in the final message varies without touching the prefix.
- B. Correct: tier-specific text at the top of the system prompt makes the system segment differ between tiers. Placing the note in the message after the last breakpoint keeps the cached prefix identical, and the note is processed fresh on each request.
- C. Incorrect: each category's subset and order becomes a separate entry that only tickets of that category can read. The system-level breakpoint still covers category-dependent tools and the tier persona text, so that large prefix is written per combination and rarely reused.
- D. Incorrect: a longer TTL only extends how long an entry lives. It does not make differing prefixes match. The tier persona text and the varying tool lists still produce different prefixes, so the 1-hour entries are written separately and rarely read.
- E. Incorrect: sorting fixes the order but not the membership. Categories still send 4 to 9 different tools, so the tools segment differs between categories, and the tier persona at the top of the system prompt still breaks the prefix after it.
5.Packaging reusable guidance without moving the prefix
If you keep the tool list fixed, you seem to lose the chance to load only what a task needs. Two packaging mechanisms keep that option without changing the prefix. The first is deferred tools: they are not included in the system-prompt prefix. When the model finds one through tool search, its definition is appended to the conversation as a tool_reference block. A small set of always-loaded tools stays cached across every turn while extra tools arrive as they are needed. The general case for loading on demand is covered in progressive discovery.
The second is Agent Skills. A Skill packages instructions, metadata and optional scripts or reference files as a directory, and it loads in stages. Only the name and description from its frontmatter are loaded at startup, as part of the system prompt. The SKILL.md body enters context only when a request matches the description, and bundled files are read only when referenced. Because the installed Skills' metadata is part of the system prompt, the set of installed Skills is part of the cached prefix. Content from a triggered Skill arrives later, in the conversation. Guidance that would otherwise be pasted into every prompt is written once and kept out of the prefix until it is needed.
| Level | When loaded | Token cost |
|---|---|---|
| Metadata (name, description) | Always, at startup, in the system prompt | ~100 tokens per Skill |
| Instructions (SKILL.md body) | When the Skill is triggered | Under 5k tokens |
| Resources and scripts | As needed | None until accessed; scripts contribute only their output |
Bundled scripts help as well. When Claude runs a validation script, the script's code never enters context. Only its output does, such as a pass message or a specific error. Distributing these packages across a team is covered in packaging Claude Code workflows.
Checkpoint 9 of 9· Match them up
A team stops pasting its review guidance and extra tools into every request. Instead it packages them as a Skill and as deferred tools. For each piece, where and when does it enter context?
Tap a term, then the definition that fits it.
Only the small Skill metadata sits in the system prompt, so it belongs to the stable cached prefix. The Skill body, script output and discovered tool definitions all arrive later in the conversation. That keeps the prefix identical while extra guidance and tools load only when needed.
“Claude loads this metadata at startup and includes it in the system prompt.”Source: platform.claude.com
Practise it for real
Pre-warm a shared system-prompt prefix and confirm from the usage fields that a follow-up request reads it.
1.Build a request with a system prompt longer than the model's minimum cacheable length, an explicit cache_control on the last system block, and a placeholder user message such as "warmup". Send it with max_tokens: 0.
Why: max_tokens: 0 writes the cache at the breakpoint without generating output, and the explicit marker keeps the entry off the placeholder.
You should see: An empty content array, stop_reason "max_tokens", and a nonzero cache_creation_input_tokens.
2.Within five minutes, send the real request with the same system prompt, the same breakpoint, the same thinking and effort settings, and a real question.
Why: A hit requires an identical prefix and an identical configuration, sent within the TTL.
You should see: cache_read_input_tokens roughly equal to the earlier write, and input_tokens covering only the question.
3.Prepend a timestamp line to the system prompt and send the real request again.
Why: This shows that dynamic content placed ahead of the breakpoint changes the prefix.
You should see: cache_read_input_tokens drops to zero and a new cache_creation_input_tokens appears.
Stuck? Get a nudge
If cache tokens stay at zero, check that the cached block is at least the minimum length for your model.
Sources
(4)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Cache hits require 100 percent identical prompt segments, including all text and images up to and including the block marked with cache control.”
↩︎ How a cached prefix is matched“Place static content (tool definitions, system instructions, context, examples) at the beginning of your prompt.”
↩︎ How a cached prefix is matched“Cache prefixes are created in the following order: tools, system, then messages.”
↩︎ How a cached prefix is matched“the automatic cache breakpoint uses one of the 4 available breakpoint slots.”
↩︎ How a cached prefix is matched“Place the breakpoint on the last block that stays identical across requests.”
↩︎ How a cached prefix is matched“input_tokens: Number of input tokens that were not read from or used to create a cache”
↩︎ How a cached prefix is matched“Cache writes: When new content is written to the cache (25 percent more than base input tokens for 5-minute TTL)”
↩︎ How a cached prefix is matched“Otherwise, it processes the full prompt and caches the prefix once the response starts.”
↩︎ Cache writes land when a response starts“Place the cache_control breakpoint on the last block that is shared with the follow-up request”
↩︎ Cache writes land when a response starts“Set max_tokens: 0 in your request.”
↩︎ Cache writes land when a response starts“Use explicit block-level breakpoints when you need to cache different sections with different change frequencies.”
↩︎ Layering content by change frequency“Adding more cache_control breakpoints doesn’t increase your costs”
↩︎ Layering content by change frequency“512 tokens for Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5”
↩︎ Layering content by change frequency“Cache entries with longer TTL must appear before shorter TTLs”
↩︎ Layering content by change frequency“continue to use the 5-minute cache, because it keeps refreshing at no additional charge.”
↩︎ Layering content by change frequency“If 4 explicit block-level breakpoints already exist, the API returns a 400 error”
↩︎ Layering content by change frequency“Verify that the keys in your tool_use content blocks have stable ordering”
↩︎ Changes that break the prefix“Verify that tool_choice, image usage, the thinking configuration, and output_config.effort remain consistent between calls.”
↩︎ Changes that break the prefix“Prompt caching covers the full prefix: tools, system, and messages (in that order), up to and including the block designated with cache_control.”
↩︎ Key concept“Otherwise, it processes the full prompt and caches the prefix once the response starts.”
↩︎ Exam trap 1“The lookback does not find stable content behind the breakpoint; it only finds entries that earlier requests wrote at their own breakpoints.”
↩︎ Exam trap 2“Cache entries with longer TTL must appear before shorter TTLs”
↩︎ Exam trap 4“automatic caching places the breakpoint on the last block, which here is the placeholder.”
↩︎ Checkpoint“a 1-hour cache entry must appear before any 5-minute cache entries”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/prompt-cachingOfficial docs
“Claude Code holds all but the first for up to 5 seconds by default”
↩︎ Cache writes land when a response starts“Switching models recomputes the entire request even when the content is identical.”
↩︎ Changes that break the prefix - 3.https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-cachingOfficial docs
“a change at one level invalidates that level and everything after it”
↩︎ Changes that break the prefix“The prefix is untouched, so prompt caching is preserved.”
↩︎ Packaging reusable guidance without moving the prefix“a change at one level invalidates that level and everything after it”
↩︎ Exam trap 3“The cache follows a prefix hierarchy (tools → system → messages), so a change at one level invalidates that level and everything after it”
↩︎ Checkpoint - 4.
“Claude loads this metadata at startup and includes it in the system prompt.”
↩︎ Packaging reusable guidance without moving the prefix“until a Skill is triggered, only its name and description occupy context.”
↩︎ Packaging reusable guidance without moving the prefix“Scripts run through bash, and only their output enters context.”
↩︎ Packaging reusable guidance without moving the prefix“Skills load on demand, so you don’t have to repeat the same guidance across conversations.”
↩︎ Packaging reusable guidance without moving the prefix