Prompt reuse: caching, modules, Skills

Three kinds of reuse, three different problems

They work together. A modular system prompt assembled in a fixed order produces a stable prefix, which is what caching needs. Skills keep specialised procedures out of that prefix until they are relevant, so the always-on part stays small (context budgeting is covered in 2.4).

Prompt caching: pay once for a stable prefix

Prompt caching stores the processed form of a prompt prefix so later requests that start with the same prefix skip that work. The prefix is built in a fixed order — tools, then system, then messages — and a change at one level invalidates that level and everything after it. Changing a tool definition therefore throws away the whole cache; adding an image affects only the messages.

There are two ways to turn it on. Automatic caching is a single top-level cache_control on the request; the breakpoint moves forward with a growing conversation, which the docs recommend for chat. Explicit breakpoints put cache_control on individual blocks — up to four per request — so sections that change at different rates are cached separately. Place each breakpoint on the last block that is identical across requests. The system looks back at most 20 blocks from a breakpoint for an earlier cache entry, so very long agent turns may need a second breakpoint.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=TOOLS,                                  # stable: first in the prefix
    system=[
        {"type": "text", "text": REBOOKING_POLICY,    # changes quarterly
         "cache_control": {"type": "ephemeral", "ttl": "1h"}},
        {"type": "text", "text": TODAYS_DISRUPTIONS,  # changes daily
         "cache_control": {"type": "ephemeral"}},     # 5-minute default
    ],
    messages=[{"role": "user",
               "content": f"Now: {now}. Passenger: {query}"}],  # volatile, last
)

u = response.usage
total_in = u.cache_read_input_tokens + u.cache_creation_input_tokens + u.input_tokens
log.info("cache hit ratio %.0f%%", 100 * u.cache_read_input_tokens / total_in)

Two details in that code are easy to miss. Longer-lived entries must come before shorter ones, so the one-hour breakpoint sits above the five-minute one. And input_tokens in the response counts only the tokens after the last breakpoint; true input is the sum of the three fields. A dashboard that reads input_tokens alone will show a suspiciously cheap service.

[system]
Current time: 09:41:07
Agent: Sam (id 5521)
You are the disruption desk
assistant for Aurora Air...
<rebooking_policy>
...40,000 tokens...
</rebooking_policy>
  ← cache_control here
[user]
Passenger question...

[system]
You are the disruption desk
assistant for Aurora Air...
<rebooking_policy>
...40,000 tokens...
</rebooking_policy>
  ← cache_control here
[user]
Current time: 09:41:07
Agent: Sam (id 5521)
Passenger question...

Modular prompts: write once, compose everywhere

A modular prompt is assembled from named, versioned sections — a brand-voice module, a data-handling policy, a refusal policy, an output-format module — each owned by one team and reviewed like code. Services compose the modules they need in a fixed order and add their own task section. This extends the template idea from 2.2 from one prompt to a fleet of them.

• One source of truth. Legal changes the data-handling module once; every service picks it up on its next release instead of relying on ten teams to copy the edit.
• Testable units. Each module change runs against every consuming service’s eval set before release, so a harmless-looking wording change cannot quietly break a downstream workflow.
• Cache-friendly by construction. Assemble modules from most stable to least stable. Two services only share a cache entry if their prefixes are byte-identical and they run in the same workspace, so a module shared at the top of the prompt, with identical tools, is where cross-service cache reuse can happen.
• Traceable. Log the module versions with each request, so an output can be traced to the exact prompt that produced it.

Agent Skills: expertise that loads on demand

An Agent Skill is a folder with a SKILL.md file — YAML frontmatter with a name and a description, then instructions — plus any reference files and scripts it needs. Anthropic’s engineering post compares writing one to putting together an onboarding guide for a new hire. The design idea is progressive disclosure: Claude sees only the metadata of every installed Skill, reads the instructions when a task matches, and opens further files or runs scripts only if the instructions call for them.

The authoring guide makes a few rules that carry straight into exam reasoning. The description must say what the Skill does and when to use it, in the third person, because it is injected into the system prompt and is the only thing Claude uses to choose. Keep the SKILL.md body under 500 lines and link reference files one level deep. Prefer bundled scripts for fragile, exact operations: a script runs without its code entering context, and gives the same result every time. And build evaluations first — measure Claude without the Skill, then write just enough to close the gap.

---
name: formatting-regulatory-submissions
description: Formats clinical study summaries to our
  submission template and validates section numbering.
  Use when drafting or checking regulatory submission
  documents, CTD modules or study summaries.
---
# Formatting regulatory submissions

1. Read TEMPLATE.md for the required section order.
2. Draft the document following that order.
3. Run: python scripts/validate_sections.py draft.docx
4. Fix every error the script reports, then re-run.

For terminology rules, see GLOSSARY.md.

Traps the wrong answers are built from

You should now be able to

• Lay out prompts from stable to volatile and place cache breakpoints on the last stable block.
• Choose between automatic caching, explicit breakpoints and the one-hour lifetime.
• Verify caching with cache_read_input_tokens and cache_creation_input_tokens and compute true input.
• Design modular, versioned prompt sections that one team owns and many services reuse.
• Explain Skill progressive disclosure and write a description that triggers reliably.
• Deploy Skills per surface, with version pinning and security and retention review.