/prompt-caching-patterns

name: prompt-caching-patterns
description: "Anthropic API prompt caching: TTL, breakpoints, stacking, invalidation, hit rate. Triggers: prompt caching, cache_control, cache breakpoint, cache TTL, hit rate."
effort: medium
user-invocable: false
allowed-tools: Read

Prompt Caching Patterns

Anthropic's prompt caching cuts input-token cost by ~90% on cached prefixes and reduces latency. Worth learning because one mistake (putting a dynamic value before a stable prefix) disables the whole cache.

Cache Mechanics

• **TTL**: default 5 minutes; `ttl: "1h"` for 1-hour cache (higher base cost but longer-lived).
• **Minimum size**: 1024 tokens per cache block for Sonnet/Opus, 2048 for Haiku.
• **Max breakpoints**: 4 per request.
• **Order matters**: everything BEFORE a `cache_control` block is part of that cache key. Dynamic content AFTER the cached block doesn't break the cache.

Anatomy of a Cached Request

from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_SYSTEM_PROMPT,  # stable across requests
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": LARGE_DOCUMENT_CONTEXT,
                 "cache_control": {"type": "ephemeral"}},
                {"type": "text", "text": user_question}  # dynamic
            ]
        }
    ]
)

Layering Pattern (4 breakpoints)

[ system prompt              ] ← breakpoint 1 (most stable)
[ tool definitions           ] ← breakpoint 2
[ long reference docs        ] ← breakpoint 3
[ conversation history up to turn N ] ← breakpoint 4
[ current user message       ] ← not cached (dynamic)

Put the MOST stable content earliest. A change to breakpoint 2 invalidates 3 and 4.

Anti-patterns

| Pattern | Problem | Fix | |---------|---------|-----| | Timestamp in system prompt | Every request is unique | Remove timestamp, or put it AFTER the cache block | | User name inserted into cached text | Cache misses per user | Inject user name AFTER the cache block | | Reordering tool definitions across requests | Cache invalidated | Sort tools deterministically | | Retrying with exponential jitter that changes prompt | Cache miss on retry | Keep the exact same prefix on retries | | Caching <1024 tokens | Silently uncached | Merge with adjacent content or drop the breakpoint |

Measuring Hit Rate

Response includes:

response.usage.cache_creation_input_tokens  # written this request
response.usage.cache_read_input_tokens      # read from cache (billed ~10%)
response.usage.input_tokens                 # not cached

Target ratio for a well-tuned loop: `cache_read / (cache_read + input) > 0.7`. Below that, you're leaving money on the table.

When NOT to Cache

• One-shot calls (cost of writing cache > savings)
• Prompts under ~1500 tokens
• Content that changes every request (user input, current weather, live data)
• Hot path with <1 request per 5 min (cache expires unused)

TypeScript SDK

const response = await anthropic.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  system: [
    { type: "text", text: LONG_SYSTEM, cache_control: { type: "ephemeral" } }
  ],
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: LARGE_CONTEXT, cache_control: { type: "ephemeral" } },
        { type: "text", text: userQuestion }
      ]
    }
  ]
});

Related

• `claude-api` skill — full Anthropic SDK patterns
• `llm-ops-engineer` agent — production caching strategy
• Anthropic docs: https://docs.claude.com/en/docs/build-with-claude/prompt-caching