Purpose
The source argues that cost and performance do not have to be traded off. Most applications improve on
both by (1) hitting the prompt cache more, (2) deleting instructions that patched older model weaknesses,
and (3) setting effort to what the task actually needs. Anthropic packaged this guidance into the
claude-api skill; this skill is the manual procedure plus pointers to those commands.
When to use
- API spend is rising, or cache reads are a small share of input tokens.
- You upgraded the model ID but kept prompts, skills, or tool descriptions written for an older model.
- You need to pick a model and effort level and have (or can build) an eval.
- Unattended workloads run synchronously at full price.
Instructions
1. Prompt cache
- Measure first: check hit rates in Claude Console cache diagnostics, which explain misses; the cache
diagnostics API shows where two requests diverged.
- Order every request static-first: tools, then system prompt, then the growing conversation.
- Keep the prefix byte-exact. Remove timestamps, IDs, and other volatile values; make tool definitions
render in a stable order (tools render at the top, so any change breaks the cache).
- Defer rarely used tools with
defer_loading so they stay out of the cached prefix until tool search
finds them.
- Send mid-conversation system prompt changes as messages instead of editing the system prompt.
- Don't change effort or thinking settings mid-conversation (they are part of the prefix). The source
notes Opus 5 and Fable 5.1 allow mid-conversation effort updates without breaking the cache.
- Fork carefully: subagents and branches share the parent's cache only with a byte-identical prefix, the
same model, and the same effort.
- Respect the TTL (5 minutes by default). For long tool or subagent waits, consider a 1-hour TTL on the
prefix. A cache rewrite costs 1.25x input price (2x for a 1-hour cache).
- Move the cache breakpoint as the conversation grows, or use automatic caching on the last cacheable
block. Pre-warm at session start with a
max_tokens: 0 request carrying an explicit breakpoint.
- Change model or effort only when the cache is already broken anyway (for example at compaction).
Full checklist: references/prompt-cache-checklist.md.
2. Instructions (prompt audit)
- Scan prompts, skills, tool descriptions, and Claude Code config (CLAUDE.md, skills) for the anti-patterns
in references/prompt-anti-patterns.md.
- Remove or rewrite each hit; delete dated configuration such as manual thinking budgets that the
platform may reject after an upgrade.
- Or run
/claude-api prompt-audit to do this automatically.
3. Effort
- Sweep effort levels on your eval to learn the task's shape. A flat cost-performance curve on a
non-saturated eval means thinking compute is not the bottleneck; more effort won't help.
- Test a stronger model at lower effort; it can beat a weaker model at high effort.
- Watch both failure modes: too high overthinks (cost, latency, sometimes lower quality); too low stops
before gathering enough evidence (fewer tool calls, skipped checks).
/claude-api hillclimb automates the search: it splits the eval into train/test, proposes config
changes, and reads failing train examples to fix them.
4. Holistic audit
Run /claude-api cost-optimize. It finds token usage from organization usage and cost reports (with an
Admin API key), logged usage objects, or by reading request-building code, then ranks levers: prompt
caching, trimming request content (including prompt-audit), bounding output, and batching unattended work
with the Batch API. Record findings with templates/cost-audit-report.md.
Benchmark numbers quoted in the source are in
references/benchmark-results.md.
Examples
Low cache hit rate in an agent
Diagnostics show the request diverges at the tool list. Tools are built from a dict whose order varies.
Sort tool definitions deterministically, move a per-request timestamp from the system prompt into the
latest user message, and defer three rarely used tools with defer_loading.
Model migration
After switching from an older Opus to Opus 5.5, run /claude-api prompt-audit. It flags "double-check
your work", "Be maximally thorough", a manual scratchpad section, and a retired thinking-budget setting.
Remove them, then rerun the eval.
Choosing a configuration
Run /claude-api hillclimb with the support eval. Compare a stronger model at low effort against a
cheaper model at low effort plus added routing rules, and keep whichever wins on the held-out test set.
1---2name: api-cost-performance-tuning3description: Cut Claude API cost while holding or improving quality using the three levers from the Claude Platform best-practices article (September 2026) - maximize prompt cache hits, remove legacy prompting anti-patterns when moving to frontier models, and calibrate effort to the task - plus the claude-api skill commands that automate them (/claude-api prompt-audit, /claude-api cost-optimize, /claude-api hillclimb). Use when an API application's spend is high, cache hit rates are low, a prompt was written for an older model, or you need to choose model and effort level against an eval.4metadata:5 source: https://skillmd.com/skills/uygnoey/api-cost-performance-tuning6---78## Purpose9The source argues that cost and performance do not have to be traded off. Most applications improve on10both by (1) hitting the prompt cache more, (2) deleting instructions that patched older model weaknesses,11and (3) setting effort to what the task actually needs. Anthropic packaged this guidance into the12`claude-api` skill; this skill is the manual procedure plus pointers to those commands.1314## When to use15- API spend is rising, or cache reads are a small share of input tokens.16- You upgraded the model ID but kept prompts, skills, or tool descriptions written for an older model.17- You need to pick a model and effort level and have (or can build) an eval.18- Unattended workloads run synchronously at full price.1920## Instructions2122### 1. Prompt cache231. Measure first: check hit rates in Claude Console cache diagnostics, which explain misses; the cache24 diagnostics API shows where two requests diverged.252. Order every request static-first: tools, then system prompt, then the growing conversation.263. Keep the prefix byte-exact. Remove timestamps, IDs, and other volatile values; make tool definitions27 render in a stable order (tools render at the top, so any change breaks the cache).284. Defer rarely used tools with `defer_loading` so they stay out of the cached prefix until tool search29 finds them.305. Send mid-conversation system prompt changes as messages instead of editing the system prompt.316. Don't change effort or thinking settings mid-conversation (they are part of the prefix). The source32 notes Opus 5 and Fable 5.1 allow mid-conversation effort updates without breaking the cache.337. Fork carefully: subagents and branches share the parent's cache only with a byte-identical prefix, the34 same model, and the same effort.358. Respect the TTL (5 minutes by default). For long tool or subagent waits, consider a 1-hour TTL on the36 prefix. A cache rewrite costs 1.25x input price (2x for a 1-hour cache).379. Move the cache breakpoint as the conversation grows, or use automatic caching on the last cacheable38 block. Pre-warm at session start with a `max_tokens: 0` request carrying an explicit breakpoint.3910. Change model or effort only when the cache is already broken anyway (for example at compaction).4041Full checklist: [references/prompt-cache-checklist.md](references/prompt-cache-checklist.md).4243### 2. Instructions (prompt audit)441. Scan prompts, skills, tool descriptions, and Claude Code config (CLAUDE.md, skills) for the anti-patterns45 in [references/prompt-anti-patterns.md](references/prompt-anti-patterns.md).462. Remove or rewrite each hit; delete dated configuration such as manual thinking budgets that the47 platform may reject after an upgrade.483. Or run `/claude-api prompt-audit` to do this automatically.4950### 3. Effort511. Sweep effort levels on your eval to learn the task's shape. A flat cost-performance curve on a52 non-saturated eval means thinking compute is not the bottleneck; more effort won't help.532. Test a stronger model at lower effort; it can beat a weaker model at high effort.543. Watch both failure modes: too high overthinks (cost, latency, sometimes lower quality); too low stops55 before gathering enough evidence (fewer tool calls, skipped checks).564. `/claude-api hillclimb` automates the search: it splits the eval into train/test, proposes config57 changes, and reads failing train examples to fix them.5859### 4. Holistic audit60Run `/claude-api cost-optimize`. It finds token usage from organization usage and cost reports (with an61Admin API key), logged usage objects, or by reading request-building code, then ranks levers: prompt62caching, trimming request content (including prompt-audit), bounding output, and batching unattended work63with the Batch API. Record findings with [templates/cost-audit-report.md](templates/cost-audit-report.md).6465Benchmark numbers quoted in the source are in66[references/benchmark-results.md](references/benchmark-results.md).6768## Examples6970**Low cache hit rate in an agent**71> Diagnostics show the request diverges at the tool list. Tools are built from a dict whose order varies.72> Sort tool definitions deterministically, move a per-request timestamp from the system prompt into the73> latest user message, and defer three rarely used tools with `defer_loading`.7475**Model migration**76> After switching from an older Opus to Opus 5.5, run `/claude-api prompt-audit`. It flags "double-check77> your work", "Be maximally thorough", a manual scratchpad section, and a retired thinking-budget setting.78> Remove them, then rerun the eval.7980**Choosing a configuration**81> Run `/claude-api hillclimb` with the support eval. Compare a stronger model at low effort against a82> cheaper model at low effort plus added routing rules, and keep whichever wins on the held-out test set.