Claude Code Cache Kit — Development skill for Claude Code

Claude Code Cache Kit

Your subagents probably re-pay for the same context over and over. This kit shows you the one setting that fixes it for long-waiting subagents, when it actually saves money, and how to check it's working.

Prices and settings checked **October 11, 2026**. They change; verify against the linked docs before relying on them.

---

1. How the cache works (30 seconds)

Every request Claude Code sends starts with the same big prefix: system prompt, tools, CLAUDE.md, history. If the next matching request lands before the cache timer runs out, that prefix is billed as a **cache read**, which is 5% of normal input on Opus 5.5 and Sonnet 5.5. If it lands after, you pay to **write** it again.

Which timer you get depends on where the work runs:

Where it runs	On a subscription	On API key / usage credits / cloud billing
Main session	1 hour	5 minutes
Fresh subagent	5 minutes	5 minutes
Fork of the conversation	5 minutes (normally)	5 minutes

So a subagent that sits waiting on a long build or test run for more than 5 minutes comes back to a cold cache and re-writes its whole prefix.

2. The setting

Merge this into your existing `settings.json`. Don't replace the file. Requires Claude Code **2.1.242+**.

{
  "subagentPromptCacheTtl": "1h"
}

This covers subagents and other work outside the main session (workflows, compaction, titles).

On an API key or usage credits, `"promptCacheTtl": "1h"` does the same for the main session. Subscriptions already get 1 hour there.

Or per agent (2.1.248+, experimental)

In one agent's `.md` file:

---
name: long-gap-researcher
description: Research tasks that pause for long-running tools
experimental:
  cacheTtl: 1h
---

• It must sit under experimental:.
• It's read from agent files only; --agents JSON ignores it.
• It's ignored while a subscription is running on paid usage credits.
• The global setting above overrides it.

Env var e