What you will be able to do
- Explain how prompt caching reuses an identical prefix and estimate its cost using write, hit and TTL pricing
- Choose between automatic caching and explicit cache_control breakpoints, and combine them within the four-slot limit
- Diagnose cache misses caused by the 20-block lookback window or by content that changes ahead of the breakpoint
- Order a prompt from most to least stable so that changes invalidate as little of the cache as possible
- Write SKILL.md frontmatter that passes validation and triggers reliably, and structure a growing Skill for progressive disclosure
Key concept
Reusable stable prefix — Reuse works when the start of a request is byte-for-byte the same as an earlier one. Caching stores that prefix so later requests skip reprocessing it. Modular layout keeps the prefix identical by putting changing content last, and Skills keep reusable instructions out of the prefix until a task needs them.
1.What prompt caching reuses and what it costs
Many production prompts open with the same few thousand tokens every time: tool definitions, a long system prompt, a block of examples, a reference document. Prompt caching lets later requests skip reprocessing that shared opening. When a request arrives with caching enabled, the system checks whether the prompt prefix up to a cache breakpoint is already cached from a recent query. On a hit it uses the cached version, which cuts processing time and cost. On a miss it processes the full prompt and caches the prefix once the response begins. The workloads that gain most are prompts with many examples, large background context, repetitive tasks with consistent instructions, and long multi-turn conversations.
A cache entry lives for 5 minutes by default, and every use refreshes it at no extra cost. A 1-hour TTL is available at 2x the base input price. The lifetime counts from the start of the request that writes or reads the entry, not from the end of its response. Generation time therefore uses up the window: if a response takes 4 minutes to stream, a follow-up that reuses the same prefix has to start within about 1 minute of that response finishing. With a 5-minute TTL, a slow agent loop or a user who pauses for a while finds the cache gone.
Caching changes the price of input tokens. Writing to the cache costs more than plain input, and reading from it costs a small fraction of plain input. Cache hits are 0.05x the base input price on Claude Opus 5.5 and Claude Sonnet 5.5, 0.025x on Claude Fable 5.1 and Claude Mythos 5.1, and 0.1x on every other model. Breakpoints themselves cost nothing. You pay only for cache writes, cache reads and uncached input, so adding breakpoints does not raise the bill.
| Model | Base input | 5m cache write | 1h cache write | Cache hits and refreshes |
|---|---|---|---|---|
| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok |
| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok |
| Claude Haiku 5.5 (prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok |
| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok |
Here is the arithmetic for a 20,000-token system prompt on Sonnet 5.5. Sent uncached, it costs $0.04 per request. The first cached request writes it for $0.05, and each hit after that costs $0.002. The write premium pays for itself on the first reuse. Short prompts are a different story. Below a model's minimum cacheable length, a prefix is not cached even if it carries cache_control. That minimum is 512 tokens on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1, and as high as 4,096 tokens on some older models such as Haiku 4.5.
Checkpoint 1 of 9· Check yourself
An agent sends a request that reads a cached system prompt with the default 5-minute TTL. Claude takes 3 minutes to stream the response. The agent wants its next request to reuse the same cached prefix. What happens?
The cache lifetime counts from the start of the request that writes or reads the entry, so generation time uses up the window: 5 minutes minus 3 minutes of streaming leaves about 2. Refreshing the entry on use is free, so there is no refresh charge.
“The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response.”Source: platform.claude.com
Sources1
2.Automatic caching and explicit cache_control breakpoints
Caching can be turned on in two ways. Automatic caching uses a single cache_control field at the top level of the request. The system places the breakpoint on the last cacheable block and moves it forward as the conversation grows, so you never edit markers by hand. On each turn, everything up to the previous request's end is read from cache, and only the new assistant reply and user message are written. Explicit breakpoints put cache_control on individual content blocks. That gives fine-grained control, for example caching sections that change at different rates.
The two methods combine. A request can have at most four breakpoints, and the automatic one takes one of those slots. If four explicit block-level breakpoints are already present, the request fails with a 400 error because no slot is left for automatic caching. It also returns 400 if the last block already carries an explicit marker with a different TTL. If that marker has the same TTL, automatic caching does nothing extra. A common combination puts an explicit breakpoint on the system prompt and lets automatic caching follow the conversation.
{
"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?" }]
}Automatic caching runs on the same infrastructure as explicit breakpoints, so the same pricing, minimum token thresholds, ordering requirements and 20-block lookback window apply. For a 1-hour TTL, write { "type": "ephemeral", "ttl": "1h" } in the same field. Prompt caching, both automatic and explicit, is supported on all active Claude models.
Checkpoint 2 of 9· Fill the gap
This request puts an explicit breakpoint on the system prompt and uses automatic caching to follow the conversation as it grows. 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. You put it at the top level of the request, not on a content block. The system then places the breakpoint on the last cacheable block. This automatic breakpoint uses one of the four breakpoint slots.
Source: platform.claude.comSources1
3.How the lookback finds earlier cache entries
A breakpoint marks the end of the prefix to look up, and most requests carry only one. When the exact prefix at the breakpoint has no entry, the system walks backward block by block. It looks for the longest prefix that an earlier request already wrote to the cache. That walk has a fixed reach of 20 positions.
Here is how that plays out over three turns. Turn 1 has 10 blocks with the breakpoint on block 10, and an entry is written there. Turn 2 has 15 blocks. Block 15 has no entry, so the walk goes back to block 10 and hits. Blocks 11–15 are processed fresh and a new entry is written at 15. Turn 3 jumps to 35 blocks, perhaps after a burst of tool calls. The walk from block 35 stops at block 16 and misses the block-15 entry by one position. Nothing has expired and nothing has been deleted. The entry is still there, but no lookup reaches it.
The fix is a second, explicit breakpoint further back, at or near the last place a write happened. Each breakpoint starts its own 20-position lookback, so a breakpoint at block 15 finds the turn-2 entry. Agent loops that add many blocks per turn, such as tool calls and tool results, are where automatic caching alone runs into this window. Watch the cache-read counts as conversations get longer.
Checkpoint 3 of 9· Check yourself
An agent loop puts a single explicit breakpoint on the final block of each request. After turns that add 25 or more tool-call and tool-result blocks, it gets cache misses, even though the early content has not changed. A teammate suggests replacing that breakpoint with top-level automatic caching. Will that stop the misses?
Automatic caching runs on the same infrastructure as explicit breakpoints, so the 20-block lookback window applies to it too. The old entry still exists, but no lookup reaches it. A second breakpoint closer to the last write starts its own 20-position lookback and finds it.
“Pricing, minimum token thresholds, context ordering requirements, and the 20-block lookback window all apply the same as with explicit breakpoints.”Source: platform.claude.com
Checkpoint 4 of 9· Exam question
A long agent session accumulates conversation turns using only automatic request-level caching. By turn 15, a cache entry exists at content block 12. By turn 25, the conversation has grown to 35 content blocks, and the current breakpoint sits on the last block. Cache reads stop matching even though the early conversation content hasn't changed. What is the best explanation and fix?
Correct answer: A — The cache lookup only scans 20 blocks backward from the breakpoint, so the block-12 entry falls outside that window; adding an explicit breakpoint further back re-establishes a match.
- A. Correct. The system checks up to 20 blocks backward from a breakpoint for a prior cache write. With the breakpoint on block 35 and the last written entry at block 12, the gap is 23 blocks, outside the lookback window, so it misses. Adding an intermediate explicit breakpoint keeps the gap within 20 blocks and restores hits.
- B. Incorrect. Automatic caching moves its breakpoint forward as a conversation grows and is designed to handle multi-turn conversations, not just a single most recent turn.
- C. Incorrect. There is no fixed block count at which cache entries are deleted outright; the miss described here is caused by the 20-block lookback window relative to breakpoint placement, not entry deletion.
- D. Incorrect. Breakpoints should be placed on the last stable block, not the first, since caching keys off the prefix ending at the breakpoint moving forward as new stable content accumulates.
Sources1
4.Modular prompt layout: stable modules first, variables last
Caching only rewards content that stays identical from one request to the next, so the order of a prompt decides how much of it can be cached. Build the prompt from modules ranked by how rarely they change. Tool definitions come first, then system instructions, then reference context and examples, then the conversation. Per-request values go at the very end. The same rule applies to reusable prompt templates with variables: put the fixed template text ahead of every slot, so filling a variable only changes the tail.
The API builds cache prefixes in a fixed hierarchy: tools → system → messages. A change at one level invalidates that level and everything after it, never what comes before. That is why order matters. An edited tool definition throws away the whole cache, while a change that only touches the messages level keeps tools and system cached.
| Change | Invalidates |
|---|---|
| Modifying tool definitions | Entire cache (tools, system, messages) |
| Toggling web search or citations | System and messages caches |
| Changing tool_choice | Messages cache |
| Changing disable_parallel_tool_use | Messages cache |
| Toggling images present/absent | Messages cache |
| Changing thinking parameters | Messages cache always; tool and system caches too on models that render the thinking configuration ahead of them |
Forcing a particular tool with tool_choice is a request setting, but it still takes part in the hierarchy. It invalidates only the messages cache. Tools and the system prompt are still read from cache, and only the messages are reprocessed. Dynamic tool discovery fits this layout too. Some tool definitions can be marked as deferred: they are held back from the request, and so stay out of the system-prompt prefix, until the model runs a tool search and finds one it needs. The definition is then appended to the conversation history, after the cached prefix, so the prefix is left alone and the cache keeps hitting.
The most common layout mistake is a variable sitting at the breakpoint. Picture blocks 1–5 holding a large static system context, and block 6 holding a timestamp plus the user message, with cache_control on block 6. The timestamp changes on every request, so the prefix hash at block 6 changes too. The lookback then walks through blocks 5 to 1 and finds nothing, because no entry was ever written there. The lookback only finds entries that earlier requests wrote. It does not cache stable content that sits behind a breakpoint. Put the breakpoint on block 5, the end of the static modules, and move the timestamp after it.
Checkpoint 5 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.
Cache prefixes follow the tools → system → messages hierarchy, and a change invalidates its own level and everything after it. Editing a tool definition therefore clears everything. Web search clears system and messages. tool_choice clears only messages. A deferred tool's definition is appended to the conversation, so the cached prefix is never touched.
“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 6 of 9· Exam question
An agentic workflow sends requests with a large tools array (15 tool definitions, cached), a cached system prompt, and growing conversation history. For one request, the developer adds tool_choice: {"type": "tool", "name": "search"} to force a specific tool call, while leaving the tools array, system prompt, and message content unchanged. What happens to prompt caching for this request?
Correct answer: A — Only the message-level cache is invalidated, so tokens up through the system prompt are still served from cache while the messages must be reprocessed.
- A. Correct. Cache invalidation cascades downward through tools, then system, then messages. A tool_choice change only invalidates the message-level cache; the tools and system caches, which sit above it in the hierarchy, remain valid and are still served from cache.
- B. Incorrect. Changing tool_choice is not equivalent to editing the tool definitions themselves; it only affects the message-level cache, not the tools-array cache.
- C. Incorrect. tool_choice does affect caching: it is one of the request properties whose change invalidates the message-level cache, so it is not entirely outside the hierarchy.
- D. Incorrect. tool_choice does not invalidate the tools-array cache; the tool definitions are unchanged. It invalidates the message-level cache instead, while the tools and system caches stay valid.
5.Agent Skills: packaging repeated instructions as SKILL.md
Caching makes a repeated prefix cheaper. Agent Skills tackle a different kind of repetition: the same procedure pasted into prompt after prompt. A Skill is a directory holding instructions, metadata and optional resources such as scripts and templates. Claude uses it automatically when a request is relevant to it. A prompt holds conversation-level instructions for a single task. A Skill is created once and loads on demand in every conversation where it applies. Anthropic provides pre-built Skills for PowerPoint, Excel, Word and PDF, and custom Skills package an organisation's own procedures.
Every Skill needs a SKILL.md file that starts with YAML frontmatter containing two required fields. The rules are strict, and a violation gets the Skill rejected:
name: at most 64 characters; only lowercase letters, numbers and hyphens; no XML tags; must not contain the reserved words "anthropic" or "claude".description: non-empty; at most 1024 characters; no XML tags.- No other field is required. There is no version suffix and no minimum description length.
Only processing-pdfs is valid. claude-pdf-helper contains a reserved word, pdf_helper uses an underscore, and PDF-Tools uses uppercase letters. Hyphens are the only separator allowed.
The description is how Claude decides to trigger the Skill. Claude matches each request against it, sometimes choosing among 100 or more available Skills. A good description therefore states what the Skill does and when to use it, including the words users actually type. "Helps with documents" names no task and no trigger, so it rarely matches. For names, a consistent gerund form such as processing-pdfs or analyzing-spreadsheets makes a library easier to scan. Avoid vague names such as helper or utils.
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---Who can use a custom Skill depends on where it lives:
| Surface | How a custom Skill is added | Who can use it |
|---|---|---|
| Claude API | Uploaded through the Skills API (/v1/skills), used via skill_id with the code execution tool | All members of the workspace |
| Claude Code | Directory with SKILL.md in ~/.claude/skills/ or .claude/skills/ | Personal (~/.claude/skills/) or project (.claude/skills/) |
| claude.ai | Zip upload in Settings > Features | Only the uploading user; not shared organization-wide or centrally managed by admins |
Skills give Claude both instructions and code, and a malicious Skill can direct tool calls or code execution that do not match its stated purpose. Install Skills only from trusted sources, and audit every bundled file before you share one.
Checkpoint 7 of 9· Match them up
A team packages one custom Skill and makes it available in four places. For each place, who can use the Skill?
Tap a term, then the definition that fits it.
Who can use a custom Skill depends on where it lives. Skills uploaded through the API are shared across the workspace. In Claude Code, ~/.claude/skills/ is personal and .claude/skills/ belongs to the project. A Skill uploaded in claude.ai stays with the user who uploaded it and is not shared across the organisation.
“Custom Skills are individual to each user. They are not shared organization-wide and cannot be centrally managed by admins.”Source: platform.claude.com
Checkpoint 8 of 9· Exam question
While authoring a custom Skill, a developer sets the frontmatter to name: claude-pdf-helper and description: "Helps with PDF forms." When Claude Code attempts to load the Skill, it is rejected. What is the most likely reason, based on the required field rules for SKILL.md?
Correct answer: A — The name contains the reserved word "claude," which is not permitted in a Skill's name field alongside "anthropic."
- A. Correct. SKILL.md name fields must contain only lowercase letters, numbers, and hyphens, and are explicitly barred from containing the reserved words "anthropic" or "claude." "claude-pdf-helper" violates that rule.
- B. Incorrect. Descriptions must simply be non-empty and no longer than 1,024 characters; there is no minimum character count requirement.
- C. Incorrect. There is no requirement for a version suffix in the name field; names just need to satisfy the character and reserved-word rules.
- D. Incorrect. Hyphens are an accepted character in the name field alongside lowercase letters and numbers; the rejection here is due to the reserved word, not the hyphen.
6.Progressive disclosure: the three loading levels of a Skill
Skills avoid filling the context window because they load in stages instead of all at once. Claude works in a virtual machine with filesystem access. Each Skill sits on disk as a directory, and Claude reads a file only when it needs it.
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (at startup) | ~100 tokens per Skill | name and description from YAML frontmatter |
| Level 2: Instructions | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| Level 3+: Resources | As needed | None until accessed | Bundled files; reference files load when read, scripts run through bash and only their output enters context |
Take a request to "extract the text from this PDF and summarize it". At startup the system prompt holds only the pdf-processing name and description. The request matches, so Claude runs cat pdf-processing/SKILL.md and the body enters context. Form filling is not needed, so FORMS.md is never read and costs nothing. Scripts go further still. When Claude runs validate_form.py, the code never enters context, only its output, such as "Validation passed". Running a script is therefore cheaper than generating equivalent code on the fly, and more consistent too.
These levels shape how a Skill should grow. Treat SKILL.md as a table of contents, and keep its body under 500 lines. As it nears that size, move detail into separate files that SKILL.md links to, such as FORMS.md, REFERENCE.md or examples.md. For Skills that span several domains, split the reference material by domain, for example reference/finance.md and reference/sales.md. A sales question then loads only the sales schema. Keep every reference one level deep from SKILL.md. When files point to further files, Claude may preview them with partial reads such as head -100 and miss information. Give any reference file over 100 lines a table of contents at the top, so a partial read still shows everything it contains.
Checkpoint 9 of 9· Put it in order
Put in order what happens when a user with the custom pdf-processing Skill installed asks Claude to "extract the text from this PDF and summarize it".
- 1.The request matches the description, so Claude runs cat pdf-processing/SKILL.md and the body enters context
- 2.At startup, only the Skill's name and description sit in the system prompt
- 3.Claude completes the task using the instructions it loaded from SKILL.md
- 4.Claude finds that form filling is not needed, so FORMS.md is never read and costs no tokens
Skills load in stages. The metadata is always present from startup. The SKILL.md body loads only after a request matches the description. Bundled files such as FORMS.md load only if the task needs them, so files the task does not need cost nothing.
“Claude reads SKILL.md from the filesystem using bash. Only then does this content enter the context window.”Source: platform.claude.com
Sources
(4)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“By default, the cache has a 5-minute lifetime. The cache is refreshed for no additional cost each time the cached content is used.”
↩︎ What prompt caching reuses and what it costs“The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response.”
↩︎ What prompt caching reuses and what it costs“Shorter prompts cannot be cached, even if marked with cache_control.”
↩︎ What prompt caching reuses and what it costs“Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.”
↩︎ What prompt caching reuses and what it costs“The system automatically applies the cache breakpoint to the last cacheable block and moves it forward as conversations grow.”
↩︎ Automatic caching and explicit cache_control breakpoints“When used together, the automatic cache breakpoint uses one of the 4 available breakpoint slots.”
↩︎ Automatic caching and explicit cache_control breakpoints“If 4 explicit block-level breakpoints already exist, the API returns a 400 error (no slots left for automatic caching).”
↩︎ Automatic caching and explicit cache_control breakpoints“Adding a second breakpoint at block 15 starts a second lookback window there, which finds the turn-2 entry.”
↩︎ How the lookback finds earlier cache entries“the system will automatically find the longest prefix that a prior request already wrote to the cache.”
↩︎ How the lookback finds earlier cache entries“Place static content (tool definitions, system instructions, context, examples) at the beginning of your prompt.”
↩︎ Modular prompt layout: stable modules first, variables last“The timestamp differs, so the prefix hash at block 6 differs.”
↩︎ Modular prompt layout: stable modules first, variables last“Prompt caching optimizes your API usage by allowing resuming from specific prefixes in your prompts.”
↩︎ Key concept“The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response.”
↩︎ Exam trap 1“Cache breakpoints themselves don't add any cost.”
↩︎ Exam trap 2“The system checks 20 positions (blocks 35 through 16) and finds nothing.”
↩︎ Prediction“Pricing, minimum token thresholds, context ordering requirements, and the 20-block lookback window all apply the same as with explicit breakpoints.”
↩︎ Checkpoint - 2.https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-cachingOfficial docs
“Deferred tools are not included in the system-prompt prefix.”
↩︎ Modular prompt layout: stable modules first, variables last“When the model discovers a deferred tool through tool search, the definition is appended inline as a tool_reference block in the conversation history.”
↩︎ Modular prompt layout: stable modules first, variables last“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 - 3.
“Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations.”
↩︎ Agent Skills: packaging repeated instructions as SKILL.md“Must contain only lowercase letters, numbers, and hyphens”
↩︎ Agent Skills: packaging repeated instructions as SKILL.md“The description must include both what the Skill does and when Claude should use it.”
↩︎ Agent Skills: packaging repeated instructions as SKILL.md“Custom Skills are shared workspace-wide: all workspace members can access them.”
↩︎ Agent Skills: packaging repeated instructions as SKILL.md“Use Skills only from trusted sources: those you created yourself or obtained from Anthropic.”
↩︎ Agent Skills: packaging repeated instructions as SKILL.md“until a Skill is triggered, only its name and description occupy context.”
↩︎ Progressive disclosure: the three loading levels of a Skill“the script code itself never enters context”
↩︎ Progressive disclosure: the three loading levels of a Skill“Cannot contain reserved words: "anthropic", "claude"”
↩︎ Exam trap 4“Custom Skills are individual to each user.”
↩︎ Exam trap 5“Custom Skills are individual to each user. They are not shared organization-wide and cannot be centrally managed by admins.”
↩︎ Checkpoint“Claude reads SKILL.md from the filesystem using bash. Only then does this content enter the context window.”
↩︎ Checkpoint - 4.
“Claude uses it to choose the right Skill from potentially 100+ available Skills.”
↩︎ Agent Skills: packaging repeated instructions as SKILL.md“Keep SKILL.md body under 500 lines for optimal performance”
↩︎ Progressive disclosure: the three loading levels of a Skill“Keep references one level deep from SKILL.md.”
↩︎ Progressive disclosure: the three loading levels of a Skill“For reference files longer than 100 lines, include a table of contents at the top.”
↩︎ Progressive disclosure: the three loading levels of a Skill