Estimates input and output token usage for a described agentic workflow, surfaces the dominant cost drivers, and suggests max_tokens budget controls per component. Use when planning a new Claude API integration, sizing a cost budget for a feature, or diagnosing why a workflow's token usage is higher than expected.
Pack api-builderTier standardJob Build on the Claude APIv1.0.0
In Claude Code, with the api-builder plugin installed, invoke it as:
/api-builder:token-budget-estimator
Try it
A realistic prompt from the skill's acceptance evals:
We're planning a Claude agent that triages inbound support tickets for Northwind. System prompt is about 6,000 characters of instructions plus 4 few-shot examples of about 1,500 characters each. Each session averages 8 tool calls: 3 calls to search_kb return about 3 KB of JSON each, and 5 calls to get_ticket_history return about 10 KB of JSON each. We keep the full conversation history. Final output is a 200-word triage note. We'll run around 5,000 sessions a day. Estimate the token budget.
What a good result looks like
Ranges over false precision. "~2,000–4,000 tokens" is more honest than "3,142 tokens" when you're working from a description. Use ranges when working from descriptions, tighter estimates when working from actual content.
The table beats the total. A single "~50,000 tokens per session" is nearly useless — the table that shows context accumulation accounts for 40,000 of those gives the developer somewhere to act.
Name the optimization target. Don't list five optimizations without ranking them. The one that saves 80% of the dominant component beats the one that shaves 5% off a small component.
How it's checked
Measured against plain Claude Code (2026-10-23): it met 76% of its checks, against 52% without it, and a blind judge preferred it. How skills are checked
20 assertions across 3 acceptance evals, and 7 trigger queries. Every skill's checks
What the output must do
Produces a component table (system prompt, few-shot examples, tool definitions, tool results, context accumulation, output, total per session), not a single total
Estimates from the description are ranges, not falsely precise single numbers like '3,142 tokens'
Uses ~4 chars/token for prose and ~3 chars/token for the JSON tool results
Names the single dominant cost driver (likely accumulated tool results / context re-sent across turns) and explains why it dominates
Gives exactly three concrete controls ranked by expected savings, with specific API parameters (max_tokens, cache_control, truncating or paginating tool results)
The rough cost estimate states its pricing-tier assumption rather than guessing silently
Does not invent workflow components, session counts, or payload sizes not in the prompt
Catches that 1,200 applications a round for three rounds is 3,600 a year, not 4,800, and bases the yearly figure on 3,600 (or shows both and flags the error)
Notes that the pilot's scoring stage used the 2,000-character draft rubric, so its measured stage 2 input understates the final 8,000-character rubric (by roughly 1,500 tokens on every model call in the loop), and adjusts for it or flags it
Identifies the scoring stage, on the large model with the history re-sent on every tool-call turn, as the dominant cost
Uses the supplied planning prices, giving roughly $0.07 to $0.13 per application and roughly $250 to $470 a year at 3,600 applications
States whether the estimate fits the $400 annual cap, consistent with its own figures
Does not invent prices, volumes, stages or tool calls that are not in the files
Fits about one page
Gives a rough total for the 600 comments that is consistent with the inputs: on the order of a few hundred thousand tokens in total, not millions
Points out that the page of instructions, sent with every request, makes up most of the input
Any cost figure states the price it assumes and is consistent with that price, coming to a few dollars rather than hundreds
Does not invent extra requirements such as several terms, rewrites or a number of teachers, or marks any such thing clearly as an assumption
Is a few short bullets in plain language
Answers without first asking questions
When it should and shouldn't activate
Should activate:
How many tokens will this agentic workflow use per session?
Size a cost budget for our new Claude integration before we build it
Our agent's token usage is way higher than expected — break down where it's going
Suggest max_tokens limits per component for this multi-turn tool-using agent
Should leave to another skill:
Exactly where should the cache_control checkpoints go in this prompt?
Put spending caps and budget kill-switches on our fleet of autonomous agents
Design the agent loop: when to stop, retry, and hand back to the user