CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards· Lessons

    Domain 2 · Lesson 11/39

    Prompt cache breakpoints and stable-prefix packaging

    Cache Breakpoints and Reusable Packaging

    19 min read
    2.17% of exam
    4 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    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.

    Explicit breakpoint on the system prompt plus automatic caching for the conversationjson
    {
      "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?" }]
    }

    Checkpoint 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?

    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?

    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?

    Sources12

    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.

    A billing assistant's request, ordered slowest to fastest, with breakpoint placement
    LayerChangesBreakpointWhat it protects
    Tool definitions and system instructionsEvery few monthsOn the last system blockThe tools-and-system entry still hits after the digest below it is regenerated
    20,000-token pricing digestOnce a dayOptional, at the end of the digestLets sessions across the day share the digest
    Customer account summaryOnce per sessionOn the final block of the summaryTurns 2 to 15 of a session read everything through the summary
    Running conversationEvery turnAutomatic caching, or noneThe 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.

    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?

    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)

    0 of 2 selected

    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.

    What each change invalidates
    ChangeInvalidates
    Modifying tool definitionsEntire cache (tools, system, messages)
    Toggling web search or citationsSystem and messages caches
    Changing tool_choiceMessages cache
    Toggling images present/absentMessages cache
    Changing thinking parametersMessages cache always; tool and system caches too on some models
    Changing output_config.effortCan 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.

    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)

    0 of 2 selected

    Sources312

    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.

    When each level of a Skill enters context
    LevelWhen loadedToken cost
    Metadata (name, description)Always, at startup, in the system prompt~100 tokens per Skill
    Instructions (SKILL.md body)When the Skill is triggeredUnder 5k tokens
    Resources and scriptsAs neededNone 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.

    Sources34

    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. 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. 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. 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. 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. 2.
      “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. 3.
      “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. 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

    Ready to test yourself?

    Practise Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.