Analyzes a prompt or conversation structure and identifies the highest-value cache breakpoints — where to insert cache_control checkpoints to minimize repeated token processing. Use when designing or optimizing a Claude API integration that uses prompt caching, when input costs are dominated by a static system prompt or few-shot block, or when a multi-turn conversation reprocesses the same context on every turn.
Pack api-builderTier standardJob Build on the Claude APIv1.0.0
In Claude Code, with the api-builder plugin installed, invoke it as:
/api-builder:prompt-caching-advisor
Try it
A realistic prompt from the skill's acceptance evals:
Our Claude contract-review service on Sonnet sends this on every request: a system prompt of about 9,000 characters of review instructions, then a 'reference' block with our 40,000-character clause library, then a line 'Today's date: {now}' appended to the end of that reference block, then 6 fixed few-shot examples (~12,000 characters), then the user's uploaded contract (varies per request). It's single-turn, roughly 2,000 requests a day. Where should the cache_control breakpoints go?
What a good result looks like
Never cache dynamic content. A user query, a timestamp, a database result retrieved per-request — these must not appear in a cached block. If the user's structure embeds dynamic content in an otherwise static block, flag it before recommending the cache.
One breakpoint per logical boundary. A system prompt with three sections (instructions, reference docs, examples) can have up to three breakpoints. More than four breakpoints on a single request is a signal the structure needs rethinking.
The last block caches everything before it. This is the most common misunderstanding — the cache breakpoint is not a marker for just that block, it's a marker for the entire prefix up to that point.
How it's checked
Measured against plain Claude Code (2026-10-23): it met 78% of its checks, against 66% without it, and a blind judge preferred the agent without it. How skills are checked
19 assertions across 3 acceptance evals, and 7 trigger queries. Every skill's checks
What the output must do
Flags that the per-request timestamp appended to the reference block makes that block dynamic and would cause every request to miss, and recommends moving it out of the cached prefix before caching
No recommended cached block contains dynamic content — the user's contract and the date stay outside every breakpoint
Shows an annotated messages/system structure with each cache_control placement marked and commented
Explains that a breakpoint caches the entire prefix up to and including that block, not just the block itself
Uses at most three breakpoints, one per logical boundary
Checks block sizes against the Sonnet minimum (~2,048 tokens) using ~4 characters per token before recommending a cache
Gives a cache strategy summary paragraph with what is cached, why, expected hit rate, and the dominant cost driver before and after
Does not invent prompt sections, request volumes, or models beyond those in the prompt
Identifies that the first system block holds the user's name and role plus a timestamp, which change on every request and sit at the very start, so nothing after them can be reused; the fix moves them after the cached content or out of the cached prefix
Notes that the tools list differs by role and comes before the system prompt in the cached prefix, so students and instructors get separate cache entries, or recommends one stable tools list
Does not adopt the dev lead's breakpoint-on-everything plan; the corrected function uses no more than four breakpoints and the note gives the per-request limit as the reason
Puts a breakpoint after the shared static content (handbook and few-shot examples) and one on the latest conversation turn, or the case study, so each 12-turn session reuses its earlier turns
Does not give an exact monthly saving, since the files give no daily request volume or prices; any figure is tied to stated assumptions
Provides a corrected build_request, and the note is under 250 words
Says to keep the unchanging part (style guide and manuscript) at the start of every request and mark it to be cached, with the changing question after it
Warns that editing the manuscript between questions means the cached copy no longer matches and has to be rebuilt, or that the cache expires after a few minutes unused, so it pays to ask several questions in one sitting on an unchanged draft
Does not invent a dollar figure or percentage saving for their bill
Uses two or three sentences in plain language
Answers without first asking questions
When it should and shouldn't activate
Should activate:
Where should I put cache_control in this messages array?
Our input costs are dominated by a static 10k-token system prompt — how do we cache it?
Every turn of our chat agent reprocesses the same docs; help me place cache breakpoints
Why is our prompt cache hit rate near zero? Here's the request structure
Should leave to another skill:
Estimate how many tokens per session our research agent will use and what drives it
Set a per-agent spending cap and kill switch for our autonomous agents
Size max_tokens for each component of this agentic workflow