Prompt Cache Agent Harness

Why This Skill Exists

Long-running agents often carry a lot of repeated context: tool manifests, system instructions, project policy, prior summaries, and durable memory. Prompt caching can make those loops cheaper and faster, but only when the reused prefix stays stable.

This skill turns that concern into a small local workflow. It helps an operator plan a cache-friendly prompt spine, inspect captured Claude usage metadata, and produce a report that separates cache behavior from durable memory design.

Who It Is For

This package is for practitioners and builders who are experimenting with persistent Claude agents and want answers to practical questions:

• which parts of the prompt should stay stable?
• did the warm run actually read from cache?
• are cache writes dominating the cost?
• did dynamic memory invalidate the cached prefix?
• what should move before or after the cache boundary?

End-To-End Workflow

1. Design the agent prompt as named layers.
2. Keep tools, system instructions, and stable reference context before the cache boundary.
3. Keep user-specific memory, retrieval snippets, and current-turn inputs after that boundary unless they are intentionally stable.
4. Run the agent loop and save redacted usage metadata outside the repo.
5. Feed the captured artifacts into scripts/prompt_cache_report.py.
6. Read the report before changing prompts, tools, or memory placement.

The package does not call Anthropic directly. That keeps secrets, raw transcripts, and provider responses out of the public handbook.

What The Helper Checks

The helper reads JSON or JSONL run artifacts and reports:

• input tokens
• cache-write tokens
• cache-read tokens
• output tokens
• latency
• cache-read share
• cache-write share
• optional input-cost estimate from supplied pricing values
• changes to stable_layer_hash
• changes to dynamic_memory_hash

Minimal Artifact

{
  "label": "warm-run",
  "latency_ms": 2800,
  "input_tokens": 18000,
  "cache_creation_input_tokens": 1200,
  "cache_read_input_tokens": 14500,
  "output_tokens": 900,
  "stable_layer_hash": "tools-system-reference-v1",
  "dynamic_memory_hash": "retrieval-42"
}

Example Command

python3 scripts/prompt_cache_report.py \
  --input ~/.codex/state/prompt-cache-agent-harness/inputs/run-pair.jsonl \
  --output ~/.codex/state/prompt-cache-agent-harness/reports/cache-report.md

Add pricing values only when you have current pricing from the provider:

python3 scripts/prompt_cache_report.py \
  --input ~/.codex/state/prompt-cache-agent-harness/inputs/run-pair.jsonl \
  --base-input-usd-per-mtok 3.00 \
  --cache-write-usd-per-mtok 3.75 \
  --cache-hit-usd-per-mtok 0.30

How To Read It In The Handbook

This package is a Practitioner example of a local-first Codex skill:

• SKILL.md defines when Codex should invoke it
• scripts/prompt_cache_report.py provides deterministic report generation
• references/source-notes.md explains the first-party source boundary
• agents/openai.yaml provides display metadata for compatible runtimes

The learning outcome is the design boundary: prompt caching rewards stable prefixes, while durable memory decides what should be recalled. A good agent loop needs both ideas, but they should not be collapsed into one hidden history blob.