name: lower-anthropic-bill
description: Use when a developer wants to cut Claude or Anthropic API spend: "lower my Anthropic bill", "audit my Claude spend", "find prompt cache failures", "why is cache_read zero", "can we move this from Claude to OpenAI or a local model". Audits call sites, tokenizer risk, cache structure, batchability, and route candidates before any code edits.
metadata:
understudy:
mode: interactive
safety: local-first
cli_required: false
Lower Anthropic Bill
Use this worker for the installer happy path and for any developer who arrives
with a Claude bill, Anthropic usage export, or codebase that calls the Messages
API. The first deliverable is a local audit: call-site inventory, current price
assumptions, tokenizer re-baseline risk, cache-hit opportunities, batchability,
and route candidates. Do not edit code during the audit.
Safety Gates
- Local-first. Static repo inspection and local usage-export parsing are the
default. Do not upload source, prompts, traces, completions, datasets, repo
paths, secrets, or private notes without explicit approval for that exact
action.
- No provider spend without a named surface, model, data class, row count, and
dollar envelope. Token-counting, cache probes, OpenAI migration tests, and
GEPA reflection all need approval if they call a provider. Recommend the
decision-sized test and explain its expected savings, time, and confidence;
one approval may cover the named bounded test matrix.
- No silent source edits. Adding
cache_control, changing model strings,
rewriting prompts, or adding an OpenAI route is a follow-up change after the
audit report is reviewed.
- Treat dollar values as estimates until backed by usage exports or measured
runs. Savings claims require the normal
claim.json evidence path from
../optimize-workload/SKILL.md.
Intake
Default to the current repo. Ask for at most one missing input:
- a path to the app or service that calls Anthropic;
- an Anthropic usage export, gateway capture directory, or sampled response
usage block;
- monthly call volume per route if no export exists.
If the installer prompt set the lower-Anthropic-bill goal, assume the objective
is cost reduction with no quality regression. Ask only for the target repo or
usage export if you cannot infer it.
If the developer asks to inspect billing email, invoices, receipts, or an
authenticated billing website, route that optional evidence source through
../inspect-billing-sources/SKILL.md
before estimating hotspots from bill data.
Flow
- Refresh vendor facts. Read
reference.md before quoting
prices, tokenizer changes, cache minimums, batch discounts, or OpenAI
migration advice. Re-verify online when the work will be sent externally.
- Inventory Anthropic call sites. Inspect dependencies, wrappers, env var
names, model IDs, prompt builders, tool definitions, retries, batch jobs, and
tracing. Use the scan checklist in
reference.md and surface the inventory
before recommending changes.
- Add optional bill evidence. If the developer approved email, invoice,
usage-export, or browser inspection, read the hotspot ledger produced by
inspect-billing-sources and join it to the call-site inventory. Keep
unattributed spend explicit.
- Re-baseline token risk. Flag Opus 4.7+ or newer model upgrades, because
Anthropic documents a new tokenizer that can increase token counts for the
same text. Prefer
usage blocks or /v1/messages/count_tokens on synthetic
or approved payloads; otherwise report this as a risk requiring measurement.
- Audit prompt-cache structure. Check whether stable tools, system prompts,
few-shots, schemas, documents, and long histories are eligible for caching;
whether volatile values appear before cache breakpoints; whether prefixes
meet current model minimums; and whether response usage shows
cache_read_input_tokens.
- Rank the opportunity ledger. Group findings by route and estimate
addressable spend only from explicit volume, usage exports, or clearly labeled
synthetic assumptions. Rank by addressable spend × confidence × expected
implementation leverage so a small, easy tail item does not displace the
concentrated cost center. Include confidence:
high, medium, unknown, or
pending eval. When value depends on who or what consumes an output now or
later, do not invent a universal taxonomy: expose the candidate segments and
let the developer drill into representative rows before labeling work as
low-value or removable.
- Pick candidate interventions. Start with the intervention offering the
largest expected addressable savings at sufficient quality and confidence.
Consider cache fixes, batch moves, max-token/output tightening, older or
cheaper Anthropic models, local/open-weight candidates, OpenAI routes, and
GEPA prompt repair in the order supported by the opportunity ledger—not a
fixed cheapest-first ladder. Prefer the lower-cost test only when alternatives
have comparable expected information value. Follow
../understudy/reference.md → Outcome-first
spend posture. Route model comparisons to
../compare-model-sweep/SKILL.md and GEPA
to ../optimize-workload/SKILL.md.
- Stop at the audit unless asked to implement. If the developer chooses a
fix, make one small reviewable change and verify it with the relevant usage
field or eval. Do not bundle unrelated route migrations.
- Offer anonymous savings sharing only after evidence exists. When a
value report or
claim.json supports the result, route to
../share-savings/SKILL.md. Never send prompts,
traces, repo names, company names, or contact details.
Output Standard
End with:
- repo or export inspected;
- Anthropic call-site inventory;
- tokenizer re-baseline status;
- cache-hit findings and exact invalidators, when known;
- opportunity ledger with assumptions and confidence labels;
- route candidates split into cache, batch, cheaper Anthropic, OpenAI, and
local/open-weight lanes;
- result type: audit, measured sample, migration plan, validation, or blocked;
- one recommended next local command or approval-gated test.
References
