---
name: "cost_tracking_llm"
description: "Track LLM API spend per task, model, and feature: log every call to a cost ledger, get per-feature and per-task spend reports, fire budget alerts at 70/90/100%, and evaluate whether routing-by-difficulty or prompt caching will pay off. Use when an app or agent needs cost attribution, monthly budget guardrails, or a measured plan to cut token spend."
---

# Purpose

Turn "the LLM bill went up" into an answerable question. This skill gives
an agent a working cost ledger, spend reports sliced by task/model/feature,
budget alerts, and a playbook for the two levers that cut spend:
routing by difficulty and prompt caching.

# Workflow

1. **Set up the pricing table.** Copy `assets/prices.example.json` to
   `assets/prices.json` and fill in the current per-million-token prices
   for the models you use: input, cached-input, output, and reasoning.
   Prices change constantly, so treat this file as the single source of
   truth and update it when providers reprice.
2. **Log every call.** After each LLM call, run:

   `bin/llm-cost-tracker.py log --model <id> --input <n> --output <n> --task <task-id> --feature <feature>`

   Add `--cached-input`, `--reasoning`, `--provider`, and `--outcome failed`
   when applicable. The `task` tag is what makes per-task attribution
   work, so never leave it unset.
3. **Read the report weekly.** `bin/llm-cost-tracker.py report --month YYYY-MM`
   shows spend by feature, by model, top tasks, and waste flags (high
   failure rates, one model dominating spend). The expensive feature is
   usually obvious; start there.
4. **Guard the budget.** Put `bin/llm-cost-tracker.py check-budget --budget <usd> --month YYYY-MM`
   on a cron schedule. Exit 0 is fine, 1 means warning (70%+), 2 means
   critical (90%+): throttle or reroute to cheaper models.
5. **Decide on routing or caching with numbers.** For a candidate task,
   run `bin/llm-cost-tracker.py estimate-route` with your own volume and
   difficulty mix to see whether a cascade saves money. For caching,
   check the task's cache hit rate from the report and follow
   `references/routing-and-caching-playbook.md`: Anthropic needs reuse
   twice within the TTL to beat the write premium, OpenAI caching is
   automatic, misroutes and stale routers are the failure modes.

# Output Contract

- `log` writes one JSON record per call to the ledger (default
  `~/.llm-cost/ledger.jsonl`) and prints the call's cost in USD.
- `report` prints: total calls and spend, spend by feature, spend by
  model, the 8 most expensive tasks with per-call cost, and waste flags.
- `check-budget` prints spend, budget, percentage used, and status
  (ok / warning / critical / CRITICAL exhausted), exiting 0/1/2.
- `estimate-route` prints projected daily cost for cascade vs
  always-large routing and the estimated savings.

# Operating Rules

1. Every factual claim about a provider's pricing or caching behavior
   must come from the provider's docs or pricing page, verified before
   use. Unverifiable numbers get cut, never stated confidently.
2. Log token counts, models, tags, and cost. Never log prompt or response
   text into the cost pipeline.
3. `task` is required on every logged call. "(unset)" features are
   allowed but should stay rare.
4. A model missing from the pricing table is logged with a warning and
   blank cost, not silently dropped. Add the price, then move on.
5. A routing or caching change ships only after a measured quality check
   against a baseline (always-small, always-large), not on vibes.
6. When the budget check hits critical, throttle or route cheaper first.
   A hard stop on a production path needs a human decision.