# Prompt Caching

> Designs and wires Anthropic prompt caching for Messages API calls — automatic vs explicit breakpoints, prefix ordering, TTL, minimum token thresholds, and cache-invalidation traps. Use when building Claude API integrations, agent loops, multi-turn chats, large tool/system prompts, or when the user mentions prompt caching, cache_control, or cache_read_input_tokens.

- Skill: `jcdavis131/prompt-caching` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jcdavis131/prompt-caching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcdavis131/prompt-caching/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jcdavis131 (https://skillmd.com/u/jcdavis131)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jcdavis131/prompt-caching

---


# Prompt Caching (Anthropic Messages API)

Caching reuses stable prompt prefixes; writes cost 25% more (5m TTL), reads cost 10% of base input.

Docs: https://platform.claude.com/docs/en/build-with-claude/prompt-caching

## Decision

| Mode | When |
|---|---|
| **Automatic** | Multi-turn chat; growing history should cache itself |
| **Explicit** | Static prefix + varying suffix (timestamp, user message) |
| **Both** | Long system/tools + growing conversation |

## The one rule

Place `cache_control` on the **last block whose prefix is identical** across requests you want to share. Breakpoint on a per-request suffix (timestamp, session ID) → miss every time.

## Structure

Order: **tools → system → messages**. Large stable content first; varying content last.

## Verify

Check `response.usage`: `cache_read_input_tokens`, `cache_creation_input_tokens`, `input_tokens`. Both cache fields zero → not cached (too short, prefix changed, or first request).

## Monorepo targets

- **worker**: cache tools + system; automatic on messages.
- **Experiment loops**: breakpoint before varying experiment config.
- **SME fanout**: shared charter cached; per-lane charter after breakpoint.

Do not cache: under minimum tokens, one-shot calls, prefixes that change every request.

## API shapes, TTL, invalidation, checklist, model minimums

[reference.md](reference.md)

## Pair with

- `cost-transparency` · `deterministic-core-llm-judgment` · `agent-guardrails`