skill
token-optimiser
Route the task before you run it - surface, model and budget in one card. A Claude skill for spending tokens where they earn their keep.
Set up
Skills are installed by placing their folder where your agent loads skills.
The download comes from github.com/jamiecooper4-netizen/token-optimiser itself, not from our server, so what you get is exactly what its author published.
Install instructions come from the README
README
synced Oct 23, 2026token-optimiser
Route the task before you run it. A Claude skill that picks the surface, the model and the budget in one card — then works to it.
Most token advice amounts to "be concise". That is the smallest lever there is. The expensive decisions are made in the first ten seconds — which surface is this, which model does it need, how much work is it actually worth — and they are usually made by not thinking about them at all.
The organising idea, and the reason this is not just a diet:
The goal is not fewer tokens. It is no wasted tokens. A confident wrong answer is the most expensive output there is.
What you see
▸ Triage Complex · 8/10 (B2 D2 A1 S1 C2)
▸ Run in Claude Cowork — files on disk, subagents isolate context, delegate and come back
▸ Run on Opus 5 · claude-opus-5
▸ Switch /model opus · picker → Opus 5 · "model": "claude-opus-5"
▸ Or ↓ Sonnet 5 if a rough draft is fine · ↑ Fable 5 if the spec might be wrong
▸ Budget ≤20 tool calls · caching: yes — long loop, cache the prefix, prune stale results
! C=2: context hygiene dominates cost here
Five lines, before the first tool call. Then it works to that budget.
Install
Claude Code — personal, available in every project:
git clone https://github.com/jamiecooper4-netizen/token-optimiser.git ~/.claude/skills/token-optimiser
Restart Claude Code and run /skills to confirm it loaded. For one repo only, clone
into .claude/skills/ instead and commit it — the whole team gets it on next pull.
Claude.ai / Cowork — Settings → Customize → Skills → upload token-optimiser.skill
(or a zip of this folder). On Team and Enterprise you can share it org-wide from the
same screen.
Anywhere else — SKILL.md is plain markdown. Paste it into a system prompt or
project instructions; you lose the scripts and keep the rubric.
What it decides
1 · Triage — scores the request 0–2 on five axes: Breadth, Depth, Ambiguity, Stakes, Context load.
2 · Surface — where does the material live? Conversation → chat. Repo → Claude Code. Many files or steps → Cowork. A spreadsheet, deck or doc → the app connector. A live site → Chrome. This comes before the model, because the model is a per-call cost while the surface decides what gets re-sent every turn for the whole session.
3 · Model — 0–2 Haiku 4.5, 3–5 Sonnet 5, 6–8 Opus 5, 9–10 Opus 5 at high effort.
4 · Overrides that beat the score — because averages hide the risks that matter.
D=2 or A=2 never routes below Sonnet 5 (small models fail worst on under-specified
work). S=2 never below Opus 5 (when the action is irreversible, the price delta is
rounding error). A 50×-repeated task drops a tier and gains caching plus batching. A
user-named model always wins.
5 · Budget — tool-call ceiling, output length, and whether to bother clarifying.
Tested, not asserted
python scripts/run_evals.py
| Suite | Result | What it proves |
|---|---|---|
| Rubric consistency | 13/13 | Axis scores plus overrides always produce the intended model. This one has to stay green. |
| Surface routing | 10/10 | Tasks land in the right place. Where material lives is legible in the wording. |
| Heuristic tier match | 13/15, 15/15 within one tier | The keyword fallback. Both misses under-read by one tier. |
Two things this repo will not do: quote savings it has not measured, or pretend the
keyword heuristic is the clever bit. It under-reads difficulty, because hard problems
do not announce themselves lexically — so --auto carries a deliberate upward margin,
fitted to the eval set in evals/ and still wanting a hold-out set. The accurate path
is a model scoring the axes.
Cost calculator
python scripts/estimate.py --input-tokens 40000 --output-tokens 2000 \
--cached-tokens 35000 --calls 500 --batch
| Configuration | 500-call workload |
|---|---|
| Opus 5, no levers | $125.00 |
| Opus 5 + caching + batch | $23.23 · −81% |
| Haiku 4.5 + caching + batch, where triage allows | $4.65 · −96% |
Rate arithmetic over published prices, not observed savings — the size of the prize,
not a result. Uses the count_tokens endpoint when ANTHROPIC_API_KEY is set and a
character estimate otherwise, and always says which. Rates live in
references/pricing.json, never in the prose, so there is one place to update.
The levers it points at
| Lever | Effect | Where |
|---|---|---|
| Prompt caching | cache hits ~10% of base input | references/api-levers.md |
| Batch API | −50%, async, stacks with caching | same |
| Model routing per call | cheap classifier in front of an expensive worker | same |
| Context hygiene in loops | prune stale tool results, pass paths not contents | same |
| Surface choice | the structural one — paid every turn | references/surfaces.md |
| Session discipline | targeted reads, batched calls, no narration | references/session-tactics.md |
Contributing
The most useful thing you can send is a routing miss — a real prompt where the card sent you to the wrong surface, model or budget. Every one becomes an eval case, which is how the rubric gets less wrong. There is an issue template for exactly this.
See CONTRIBUTING.md.
Layout
SKILL.md triage, surface, routing, budgets, quality floor
references/surfaces.md chat vs Cowork vs Code vs app connectors, and the cost model
references/api-levers.md caching, batch, pipeline routing, context management
references/session-tactics.md search, file and conversation discipline
references/pricing.json rates — the only place numbers live
scripts/route.py triage → surface + model (CLI and JSON)
scripts/estimate.py cost a workload across models and levers
scripts/run_evals.py test suite
scripts/log_miss.py record a routing miss locally (git-ignored)
scripts/suggest_improvements.py cluster logged misses into a reviewable proposal
evals/routing_evals.json eval cases — PRs welcome
Getting better over time
Log a routing miss when you spot one, cluster them periodically into a draft of
candidate eval cases, then read the draft and hand-merge anything real — the
rubric never edits itself, and nothing ships without passing run_evals.py and a
human looking at it. See "Getting better over time" in SKILL.md for the full loop.
Licence
MIT. Take it, fork it, strip it for parts.