usage-budget
Skill0 starsChanged 56 days agoMITView on GitHub
Work to an explicit usage budget. Estimate first, spend on the highest-value steps, check in at 50% and 80%, and stop before overspending. Use when the user sets a budget or limit ("do this in 3% of my usage", "keep it cheap", "I'm nearly out of tokens", "under 20 tool calls").
In this repository10 other files it gives its agents.
- cheap-subagentsSkill
- context-auditSkill
- limit-window-warmupSkill
- pinpointSkill
- progress-ledgerSkill
- quiet-toolsSkill
- short-answersSkill
- skillifySkill
- token-saverSkill
- workflow-optimizerSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 45
Never overrun quietly. An overrun the user agreed to is fine.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Usage budget
A task without a budget expands to fill the plan. Stating one changes how an agent works: it plans narrower, searches less, and stops to ask instead of trying a fifth approach. A 2024 study (Token-Budget-Aware LLM Reasoning) found that a token budget stated in the prompt shortens a model's chain-of-thought output with only a small loss of accuracy.
1. Put the budget in units you can count
Most hosts show plan usage to the user, not to the model. The model can't read /usage or /status for itself, so turn the user's budget into things the agent counts on its own:
| User says | Working proxy |
| "tiny", "1–2% of my limit" | ≤10 tool calls, ≤5 file reads, no subagents |
| "small", "about 5%" | ≤30 tool calls, at most one cheap subagent |
| "whatever it takes" | no cap, but still check in at the checkpoints |
These are starting points. Calibrate them against the host's meter after a few tasks. Tell the user in one line which proxy you're using.
A few budgets the host can enforce outright:
- Claude Code headless runs:
claude -p "<task>" --max-turns 10, or--max-budget-usd 2.00when billed by API. - Claude Code or Gemini CLI subagents:
maxTurns/max_turnsin the agent file. - Any API: a cap on output tokens per call.
2. Estimate before starting
List the steps with a rough cost for each. If the estimate is over budget, say so and offer the cheaper plan (narrower scope, skip the nice-to-haves, delegate, split across sessions) before spending anything.
3. Spend in value order
Locate, change, verify. Exploration is where budgets die: start from a pinpointed location (see pinpoint), read slices, don't browse.
4. Checkpoints
- At 50%: is half the work done? If not, re-plan, or tell the user now.
- At 80%: finish the smallest shippable piece, stop, and report what's left and what it would cost.
Never overrun quietly. An overrun the user agreed to is fine; a surprise one isn't.
5. Report
One line at the end: budget, spend, what's left.
Budget ≤30 tool calls: used 22. Done: fix + test. Not done: refactor of the parser (est. 15 more).Where the meters are (for the user)
| Host | Plan usage | Context |
| Claude Code | /usage | /context |
| Codex | /status, /usage | /status |
| Gemini CLI | /stats model | /stats |
Before you finish
- The budget and its proxy were stated before the work began.
- Checkpoints happened; any overrun was agreed with the user.
- The last line reports spend against budget.
Part of agent-skills · MIT · improvements welcome as issues.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.