prompt-cache-kit
Skill0 starsChanged 30 days agoMITView on GitHub
Make dynamic agents cheaper by keeping their prompt prefixes byte-identical so the prompt cache hits. Use whenever you are about to spawn subagents, forks, parallel agents or a Workflow, run /loop or ScheduleWakeup, or when the user says "save tokens", "prompt caching", "cache hit", "token usage", "ลด token". Builds a fingerprinted, byte-stable project outline locally with uv (no API key, no LLM), generates agent briefs that put that outline first and the task last, and reports per-agent cache hit rate from the local Claude Code session logs.
In this repository8 other files it gives its agents.
- dependency-vuln-explainerSkill
- design-coreSkill
- design-flowSkill
- doc-style-builderSkill
- pdf-operationsSkill
- poc-spec-driven-builderSkill
- podman-disk-reclaimSkill
- thai-mock-namingSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
Fresh agents get a
briefoutput as their prompt: Never hand-write the shared part, and never paste a different repo summary into each … - Distinctive: line 28
Keep the prefix still mid-run: Don't edit CLAUDE.md, skills or MCP config, and don't switch models, while agents are running.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Prompt Cache Kit
Claude Code already sends prompt caching on every request. A cache hit needs a byte-identical prefix, and a hit costs about 0.1× the normal input price, while a write costs about 1.25× (5m TTL) or 2× (1h TTL). Whether dynamic agents get hits depends on how you write their prompts. This skill keeps those prompts identical where it counts.
Idea borrowed from Understand-Anything: do the structural work locally and deterministically, fingerprint files so only changed ones get recomputed, and let agents read the precomputed result instead of re-reading the repo.
Tool: uv run --script ${CLAUDE_SKILL_DIR}/scripts/pcache.py <cmd>. It's stdlib only, and uv handles the Python version.
| Command | Does |
build [root] | Hashes git-visible files and re-outlines only the changed ones into .pcache/context.md, which comes out byte-stable. |
brief "<task>" [--role R] | Prints the outline, a fixed rules block, then the role and task last. |
stats [session_id] [--logs DIR] | Shows input, cache write, cache read and hit rate per agent, read from ~/.claude/projects/<cwd>/. Defaults to the newest session. |
--self-test | Runs the built-in asserts. |
Rules when running dynamic agents
- Before fanning out, run
build. It's cheap on later runs because only changed files are re-outlined. - Fresh agents get a
briefoutput as their prompt. Never hand-write the shared part, and never paste a different repo summary into each agent, because one changed byte early on costs the whole prefix. - Use a fork when the agent needs this conversation. A fork inherits the parent's cached prefix. Use a fresh agent with a brief when it doesn't, which keeps the prefix small and shared across siblings.
- Continue an agent with SendMessage instead of spawning a new one. Its history is already cached.
- Keep /loop and ScheduleWakeup delays under 3600s. Past the 1h TTL, the next turn pays a full cache write again.
- Keep the prefix still mid-run. Don't edit CLAUDE.md, skills or MCP config, and don't switch models, while agents are running.
- After the run, run
statsand report the TOTAL hit rate in one line. Agents markedcold(under 50%) mean their prompt prefix differed. Check rule 2 for them.
.pcache/ belongs in the target project's .gitignore. build prints a hint on its first run and never edits the file itself.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.