Cache Policy Designer
Design a cache policy from data ownership, freshness, privacy, invalidation, and failure requirements across browser, CDN, reverse-proxy, application, and data caches. Use when adding caching, debugging stale responses, reviewing Cache-Control behavior, reducing origin load, or deciding whether a value can be cached safely at all.
npx agentscamp add skills/cache-policy-designerInstall to ~/.claude/skills/cache-policy-designer/SKILL.md
Designs cache behavior per object and layer by identifying ownership, variation keys, freshness bounds, invalidation events, privacy constraints, stampede protection, stale-on-failure behavior, and observability. It produces explicit headers or key rules plus correctness tests rather than applying one TTL everywhere.
Design caching as a correctness contract with a performance benefit.
Workflow
- Inventory the cacheable object. Name the response or value, authoritative source, readers, writers, sensitivity, size, cost to recompute, and consequence of serving it stale.
- Map every cache layer. Trace browser, service worker, CDN, gateway, reverse proxy, framework, application, ORM, and database caches. Record which layer currently owns freshness and invalidation.
- Define identity and variation. Specify the complete cache key: resource, tenant, user or authorization class, locale, encoding, version, query shape, and any header that changes representation. Remove unnecessary variants but never collapse security boundaries.
- Choose freshness semantics. Set max age from the business freshness bound, not a convenient round number. Decide whether revalidation,
stale-while-revalidate, orstale-if-errorpreserves acceptable behavior. - Design invalidation. Identify every write or event that changes the object. Choose purge, versioned keys, tag invalidation, write-through, or bounded expiration, and state how missed events heal.
- Control concurrency. Prevent cold-key stampedes with request coalescing, locks with bounded leases, probabilistic early refresh, or jitter. Define behavior when the origin is slow or unavailable.
- Specify privacy and failure rules. Mark values that must never enter a shared cache. Define fail-open versus fail-closed, negative caching, error caching, and the maximum stale age during outages.
- Verify and observe. Test hit, miss, revalidation, invalidation, authorization variation, purge failure, origin failure, and concurrent expiry. Measure hit ratio by status, age, evictions, origin savings, stale serves, and key cardinality.
WARNING
Do not add public caching or omit authorization from a key merely to improve hit rate. Cross-user cache leakage is a security failure, not a tuning tradeoff.
Output
Return a layer-by-layer policy with key dimensions, freshness directives, invalidation events, stampede controls, outage behavior, privacy exclusions, implementation locations, verification cases, and metrics. Call out unknown writers or variation inputs that block safe caching.
Frequently asked questions
- What is the hardest part of caching?
- Correct invalidation and variation. A fast cache that serves another user's data or an obsolete business state is a correctness incident, so policy starts with ownership and change events before TTL.
- Should authenticated responses ever be cached?
- Only with an explicit private or identity-partitioned policy and verified variation keys. Shared caches must not store personalized responses unless the design proves tenant and user isolation.
Related
- 9 Best Claude Skills for Performance EngineeringCompare Claude skills for caching, Web Vitals, bundles, React renders, load tests, cold starts, CPU profiles, memory leaks, and prompt caches.
- API ArchitectUse this agent to design APIs — resource modeling, versioning, pagination, error contracts, REST vs GraphQL. Examples — designing a public API, reviewing an API spec, planning a breaking change.
- Cold Start OptimizerCut cold-start latency for serverless functions and slow-booting apps by measuring the init breakdown, then attacking the dominant phase — artifact size, eager imports, eager connections, or under-provisioned memory — instead of reflexively buying provisioned concurrency. Use when serverless p99 spikes on the first request, when a function times out during init, or when scale-to-zero is hurting user-facing latency.
- Load Test DesignerDesign a defensible load test — a realistic workload model, a deliberate test type, and SLO-tied pass/fail thresholds — instead of a meaningless tight-loop script that hammers one endpoint. Use when validating capacity or SLOs before a launch or scaling event, when sizing infrastructure, or when an existing load test reports averages that nobody trusts.
- Semantic Cache DesignerDesign a semantic cache for LLM responses — serve a cached answer when a new query is similar enough to a past one — to cut cost and latency on repetitive traffic, with the similarity threshold calibrated on real query pairs and a cache key that prevents cross-user/model leaks. Use when an LLM app sees many near-duplicate prompts (FAQs, support, search), when token spend on repetitive queries is high, or when latency on common questions matters.
- Web Vitals OptimizerDiagnose and fix Core Web Vitals — LCP, CLS, and INP — by treating real-user field data at p75 as the source of truth, using Lighthouse/WebPageTest only to find the at-fault element, script, or shift, then applying the one targeted fix per metric and re-measuring. Use when a page feels slow, scores poorly on PageSpeed/Lighthouse, or fails CWV in CrUX/RUM field data.