Profiling spend instead of reciting advice
/claude-api cost-optimize, added in Claude Code v2.1.247 on 26 August 2026, is a subcommand of the bundled claude-api skill, the same skill behind /claude-api migrate and /claude-api upgrade. Per Anthropic's commands reference, it's described plainly: run cost-optimize "to profile where your project's Claude API spend goes and propose savings from options such as prompt caching, trimming unneeded input and output tokens, batch processing, effort, and model choice, one change at a time."
That "one change at a time" framing is the point. Generic cost-cutting advice for the Claude API is easy to find and mostly the same everywhere: cache your prompts, watch your output length, consider a cheaper model. What cost-optimize does differently is look at your project's actual usage pattern first, then rank which of those generic levers is worth pulling for you specifically, rather than handing you all five at once with no sense of which matters most for this codebase.
The five levers, in the order the command checks them
Per the reference, the levers appear in this order:
- Prompt caching
- Trimming unneeded input and output tokens
- Batch processing
- Effort
- Model choice
That order isn't arbitrary. The first two levers are non-structural, applying them doesn't change what your application does or how it behaves, only how much it costs to do it. The last three are increasingly structural: batch processing changes your request pattern, adjusting effort changes how much the model reasons before answering, and model choice can change response quality outright. Checking the cheap, safe fixes first and only reaching for the ones with real trade-offs once those are exhausted is the whole design logic behind the ordering.
Prompt caching
If your project sends the same system prompt, tool definitions, or reference material on every request, and much of the claude-api skill's own reference material assumes exactly this pattern, caching is usually the single highest-leverage fix available, since a cache hit means paying a fraction of the input-token price for content that didn't need to be reprocessed. Claude Code's own prompt cache TTL settings cover the mechanics in more depth: which cache buckets exist, how long content stays warm, and what invalidates it regardless of TTL, all directly relevant background for understanding what cost-optimize is actually checking when it profiles your caching behaviour.
Trimming unneeded input and output tokens
The second lever is more manual: are you sending context the model doesn't need for this particular call, and is the model returning more than the task actually requires? Unlike caching, there's no single setting that fixes this, it's a matter of auditing what actually goes into and comes out of each request type your project makes, which is exactly the kind of profiling work cost-optimize is positioned to surface rather than leaving you to notice on your own.
Batch processing
The Claude API's batch processing lets you submit a large volume of non-time-sensitive requests together at a reduced rate, rather than paying the standard synchronous price for each one individually. It's a structural change, since batch responses aren't immediate, so it only makes sense for workloads that don't need a same-second answer: bulk classification, large-scale content generation, or any pipeline that already processes work asynchronously.
Effort
Adjusting a model's effort level trades reasoning depth for cost and latency. A call that doesn't need the model's full reasoning budget to answer correctly is paying for effort it isn't using, and the reverse is also a real risk, an effort level set too low for a genuinely hard task, costing you correctness rather than money. This is the first lever in the list where the trade-off runs both directions, not purely towards savings, which is presumably part of why the command surfaces it as a proposal to review rather than a change to blindly apply.
Model choice
The last, most structural lever. Anthropic's current lineup of Claude Opus 5, Sonnet 5 and Haiku 4.5 spans a real price range across the balanced and fast tiers, and a task running on a stronger model than it needs is the most expensive kind of mismatch to leave uncorrected. It's checked last because changing a project's model choice is the change most likely to alter output quality, and validating that a cheaper model still meets the bar takes actual re-testing, not just a config edit.
The other claude-api subcommands, for context
cost-optimize is one of five things /claude-api can run, each with its own version floor:
| Subcommand | What it does | Requires |
|---|---|---|
migrate | Updates existing Claude API code to a newer model | (no separate floor documented) |
upgrade | Moves your project's Anthropic SDK dependency across a major version | v2.1.236+ |
managed-agents-onboard | Walks through creating a new Managed Agent | (no separate floor documented) |
prompt-audit | Flags instructions written for older models across prompts, skills and tool descriptions, proposes fixes as a diff | v2.1.221+ |
cost-optimize | Profiles spend and proposes savings, one change at a time | v2.1.247+ |
Having one available doesn't guarantee another is: if cost-optimize isn't available on your Claude Code install, check claude --version before assuming the whole /claude-api skill is missing, since migrate alone has been available for considerably longer than cost-optimize has existed.
The skill itself activates automatically when your code imports anthropic or @anthropic-ai/sdk, in addition to being invocable directly by name, the same progressive disclosure behaviour every well-built skill relies on: the reference material cost-optimize draws on doesn't load into context until something actually calls for it.
Why a profiling command instead of a checklist
It's worth being explicit about what problem cost-optimize is actually solving, because the five levers themselves aren't secret. Anthropic documents caching, batch processing and effort levels individually across its own API docs, and any team running the Claude API at scale has probably already read a version of this checklist somewhere. The gap a generic checklist can't close is prioritisation: five true statements about how to save money don't tell you which one matters for this project, this month, at this traffic pattern. A project already caching aggressively gains nothing from being told to cache more; a project making a handful of low-volume calls a day has little to gain from batch processing, however real the saving is for a higher-volume workload.
That's the actual value of a command that profiles before it proposes. It reads what your project is doing, not what Claude API projects in general tend to do, and ranks the five levers by what your usage pattern shows rather than by a fixed, one-size-fits-all order. The order Anthropic documents, caching first, model choice last, is still a sensible default sequence for most projects, cheap and reversible fixes before structural ones, but the profiling step is what turns a generic list into a plan specific to your spend.
When to reach for it
Run /claude-api cost-optimize when you have a project with real, observable Claude API usage already, a review, not a design exercise for something not yet built. The command needs your project's actual usage pattern to profile against, so it's most useful periodically on an established integration, after a usage spike you weren't expecting, or as a standing check before a pricing or budget review, rather than something to run once at the start of a project when there's no traffic pattern yet to analyse.
An illustrative pass, to be clear about what "profile first" means in practice
The exact output format cost-optimize produces isn't documented beyond the one-line command description, so treat what follows as illustrative of the documented lever order rather than a real transcript. Given a project that makes frequent calls with a large, mostly-static system prompt and occasional bursts of bulk classification work, a profiling pass working through the documented levers in order would plausibly surface something like: the system prompt isn't being cached, the single fix likely to save the most before anything else is even considered; a handful of endpoints return more output tokens than their downstream consumer actually reads; the classification bursts are currently synchronous and would tolerate batch processing's latency; effort and model choice, checked last, turn out fine for this project's actual accuracy bar.
The shape of that walkthrough, cheap fixes first, structural changes only where the cheap fixes don't fully close the gap, is the part actually confirmed by Anthropic's documented lever order. The specific findings in any real run depend entirely on your project's own traffic, which is exactly why the command profiles rather than assumes.
It's a natural complement to a couple of other spend-tracking surfaces already on this site: Claude Code's modelPricing setting if your organisation reports spend at contracted rates rather than list price, and how budgets work across Claude Managed Agents sessions and deployments if the project in question runs through Managed Agents rather than the Messages API directly.
Troubleshooting
/claude-api cost-optimize isn't recognised. Confirm you're on Claude Code v2.1.247 or later with claude --version. The subcommand didn't exist before that release, and Claude Code doesn't error helpfully on an unrecognised subcommand of a skill, it's easy to mistake for the whole claude-api skill being unavailable when only this one subcommand is too new for your install.
It doesn't seem to find much to optimise. That's a legitimate outcome, not a failure: if your project already caches aggressively, trims tokens deliberately, and runs an appropriately-sized model for its workload, there may genuinely be little left on the table. Re-run it after a usage pattern changes, a new feature added significant token volume, a workload moved from real-time to batch-eligible, rather than expecting a fresh list of savings every time.
A proposed change doesn't match how I'd actually want to adjust effort or model choice. Both are trade-off levers, not pure savings, review each proposal against your own quality bar before applying it rather than accepting it automatically, the same caution that applies to any automated refactor a coding agent proposes.
I'm not sure whether it also covers a Claude Managed Agents project rather than a direct Messages API integration. The claude-api skill's reference material spans both surfaces, Messages API and Managed Agents, per its own overview, but the cost-optimize command description in Anthropic's commands reference doesn't specify which surface it profiles or whether it treats the two differently. If your project runs through Managed Agents specifically, cross-check any proposal against how budgets work across Claude Managed Agents sessions and deployments rather than assuming the levers translate identically.
Where to go next
For the caching mechanics cost-optimize's first lever is checking, see Claude Code's promptCacheTtl and subagentPromptCacheTtl settings. For the skill this subcommand belongs to, see Anthropic's open-source Claude API skill explained. For contracted-rate spend reporting, see Claude Code's modelPricing managed setting. For budget mechanics on the Managed Agents side of the Claude Platform, see how budgets work across Claude Managed Agents sessions and deployments. Browse the current catalogue at getclaudeskills.com/skills.
