agentleFS
youcislayoucisla/Agent-Foundry/skills/core/budget-guard/SKILL.md

budget-guard

Skill1 starsChanged 23 days agoMITView on GitHub

'Set a hard spend ceiling before a paid loop starts, measure each call,

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    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
  1. Distinctive:

    Every paid call consumes a finite budget.

    line 16
  2. Distinctive:

    Before the loop, estimate the worst case: items x calls per item x tokens per call.

    line 50
  3. Distinctive:

    Check the running total before the next call.

    line 56
  4. Distinctive:

    Prefer provider-reported prompt tokens for the same model when available.

    line 109

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Budget Guard

Every paid call consumes a finite budget. Decide the ceiling first, then make the loop prove it stayed under.

When to Use

  • A task runs more than one paid model call.
  • A retry or repair loop is introduced.
  • A batch processes an unknown number of items.
  • The user names a cost, token, or time limit.
  • A fallback chain can multiply attempts.
  • Agent loops and multi-step workflows.
  • Batch extraction, evaluation, or judging runs.
  • Retry policies around flaky providers.
  • Anything that could run unattended.

Procedure

1 — Set the ceiling before the first call

Name the limit in the unit you can measure:

UnitUse when
USDPrices are known per model
TokensThe provider reports usage but not cost
CallsEvery item costs roughly the same
SecondsLatency is the constraint

Record the limit in the run configuration, not in a comment.

2 — Estimate before, measure after

Before the loop, estimate the worst case: items x calls per item x tokens per call. After each call, add the reported usage. Do not estimate from input length alone; output and repairs also cost.

3 — Stop at the boundary

Check the running total before the next call. If the next call could cross the ceiling, stop. Return partial results with the amount spent and what was skipped. A hard stop is not a failure of the task; it is the guard working.

4 — Make retries count against the budget

A retry is a new paid call. A fallback is a new paid call. Include both in the same running total so the chain cannot multiply spend invisibly.

5 — Report the spend

Return: limit, spent, remaining, calls made, and items skipped. A run that says "done" without spend numbers is unaudited.

Worked example

A stop report that shows the ceiling, the spend, and what was skipped.

limit: 50,000 tokens | spent: 31,204 | remaining: 18,796
calls: 12 (2 retries, 1 fallback) | skipped items: 7
stop reason: next call could exceed the ceiling

Anti-patterns

  • Setting a budget after the run.
  • Counting input tokens only.
  • Treating retries as free.
  • Continuing because "one more call is small".
  • Stopping silently without naming what was skipped.

References

  • fields

Verification Checklist

  • A numeric ceiling exists before the first call. (step 1)
  • Usage is measured from provider responses, not guessed. (step 2)
  • Retries and fallbacks count toward the total. (step 4)
  • Exceeding the ceiling stops the loop. (step 3)
  • The final report includes spent and skipped. (step 5)

Composes With

  • fallback-model-routing — bounded chains, counted against the same budget
  • measure-first — replaces estimates with observed usage
  • execution-observability — persists cost per execution

Two Caps and Measured Input

  • Enforce a per-call cap and a per-session aggregate cap. A single global ceiling lets one call consume the whole budget.
  • Prefer provider-reported prompt tokens for the same model when available; fall back to a character estimate only on a miss.
  • Count every model attempt, including repair rounds and judge escalations. A retry that is not counted is a budget leak.
  • Report max_attempts, max_concurrency, and checkpoint_every beside the token budget; tokens alone cannot bound wall-clock or fan-out.
  • Compaction and spill change the effective prompt size. Re-estimate after either runs, not before.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.