budget-check
Pre-wave usage gate. Before launching an expensive multi-agent wave or fan-out, check the active usage block against a threshold (default 95%) via `ccusage` and return go / no-go / unknown — fail-closed, never a fabricated go. Trigger via /budget-check, or as a reflex before any
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/budget-check
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
git clone https://github.com/allemaar/open-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
/budget-check
A pre-wave usage gate. Launching a multi-agent wave is the most expensive thing an agent does — N concurrent subagents, each burning tokens. /budget-check answers one question before you spend: is the current usage window close enough to its ceiling that starting a wave is reckless? It returns go, no-go, or unknown, and it fails closed — with no usage data it returns unknown, never a convenient "go".
It is deliberately small: a concrete wrapper around the public ccusage reader, not a judgment engine. It does not add a global rule or amend your operating directives — it is a skill you call, so the gate lives at the decision point, not as standing policy.
Structured execution spec:
protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the@STAMPdate.
The check — one tool, three verdicts
The skill ships references/tools/budget-check.mjs inside its own folder. Resolve the installed skill directory and run the bundled tool, which invokes an already-installed ccusage blocks --json. Missing tools or failed launches return unknown; never acquire a package to answer this read. Supplied numeric flags require values, while omitted flags retain their defaults:
node <skill-dir>/references/tools/budget-check.mjs # go/no-go vs 95% of your historical-peak block
node <skill-dir>/references/tools/budget-check.mjs --threshold 90 # custom threshold (percent)
node <skill-dir>/references/tools/budget-check.mjs --token-limit 200000000 # explicit ceiling instead of the auto peak
node <skill-dir>/references/tools/budget-check.mjs --json # machine-readable verdict
- Ceiling =
--token-limit <N>if you pass one, else the largest historical (non-active) block's total tokens — ccusage's ownmaxnotion, i.e. "your usual peak window." Without--token-limit, the gate measures against your own historical peak — a relative signal ("am I near my personal worst window"), not your real plan budget. For a true budget gate, pass--token-limit <N>with your plan's actual token ceiling. - Verdict =
gowhen the active block is under the threshold,no-goat or over it,unknownwhen there is no usage data, no active block, or no ceiling to measure against. - Exit code =
0go ·1no-go ·2unknown — so a dispatch script can gate on it directly. - On no-go it also reports
secondsUntilWindowClearsand amin(3600, …)poll interval, so you know how long until the window resets.
How to use it
- Before a wave (a fan-out of subagents, a
prime-sweep, an orchestrated run), call/budget-check. - GO → launch the wave.
- NO-GO → trim the wave (fewer concurrent workers), wait for the window to clear (the reported interval), or proceed deliberately — your call, surfaced not forced.
- UNKNOWN → the gate cannot vouch; decide on other grounds and say so. A common, fixable cause is no inferable ceiling (a fresh environment with no historical block) — pass
--token-limit <N>with your plan's real token budget to get a meaningful gate.
This is a runtime tool — it reads your local usage logs, so it has nothing to measure in CI. The value is at the live pre-wave decision point, never in a pipeline.
Boundary
- Not
/ask-gate— that triages a handler-facing question; budget-check gates a spend. - Not
/orchestrate-modeor/multi-agent-mode— those run the wave; budget-check only decides whether it should start. - It encodes no policy and amends no directive: a skill you call, not a rule that fires.
Human output. This skill's handler-facing output obeys the human-output contract (
human-output/SKILL.md).
Next skills. On completion, run the Next Skills protocol: surface the front-matter recommendations for the caller to pick. Offer only — never auto-invoke.
Self-improvement. On completion, run the Self-Improvement Protocol: apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Files (open-skills)
-
references
-
tools
-
budget-check.mjs 6.2 KB · in bundle
-
-
-
protocol.yon 5.2 KB · in bundle
-
SKILL.md 5.4 KB
--- name: budget-check description: > Pre-wave usage gate. Before launching an expensive multi-agent wave or fan-out, check the active usage block against a threshold (default 95%) via `ccusage` and return go / no-go / unknown — fail-closed, never a fabricated go. Trigger via /budget-check, or as a reflex before any large dispatch. Not /ask-gate (governs a handler-facing question) or /orchestrate-mode and /multi-agent-mode (which run the wave) — budget-check only decides whether the wave should start. visibility: public self-improvable: true companions: - path: references/tools/budget-check.mjs optional: false why: "The required bounded ccusage wrapper and verdict engine; bundled inside this skill." triggers: - "/budget-check" next-skills: - skill: orchestrate-mode phrase: "/orchestrate-mode" why: "On GO, launch the gated multi-agent wave with isolated workers." - skill: multi-agent-mode phrase: "/multi-agent-mode" why: "On GO, proceed with delegated helper slices alongside your own work." - skill: reflect phrase: "/reflect" why: "On NO-GO, pause to decide whether to trim the wave, wait for the window, or proceed anyway." --- # /budget-check A **pre-wave usage gate**. Launching a multi-agent wave is the most expensive thing an agent does — N concurrent subagents, each burning tokens. `/budget-check` answers one question *before* you spend: is the current usage window close enough to its ceiling that starting a wave is reckless? It returns **go**, **no-go**, or **unknown**, and it **fails closed** — with no usage data it returns `unknown`, never a convenient "go". It is deliberately small: a concrete wrapper around the public [`ccusage`](https://github.com/ryoppippi/ccusage) reader, not a judgment engine. It does **not** add a global rule or amend your operating directives — it is a skill you *call*, so the gate lives at the decision point, not as standing policy. > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date. ## The check — one tool, three verdicts The skill ships [`references/tools/budget-check.mjs`](references/tools/budget-check.mjs) inside its own folder. Resolve the installed skill directory and run the bundled tool, which invokes an already-installed `ccusage blocks --json`. Missing tools or failed launches return `unknown`; never acquire a package to answer this read. Supplied numeric flags require values, while omitted flags retain their defaults: ```bash node <skill-dir>/references/tools/budget-check.mjs # go/no-go vs 95% of your historical-peak block node <skill-dir>/references/tools/budget-check.mjs --threshold 90 # custom threshold (percent) node <skill-dir>/references/tools/budget-check.mjs --token-limit 200000000 # explicit ceiling instead of the auto peak node <skill-dir>/references/tools/budget-check.mjs --json # machine-readable verdict ``` - **Ceiling** = `--token-limit <N>` if you pass one, else the largest historical (non-active) block's total tokens — ccusage's own `max` notion, i.e. "your usual peak window." Without `--token-limit`, the gate measures against *your own historical peak* — a relative signal ("am I near my personal worst window"), not your real plan budget. **For a true budget gate, pass `--token-limit <N>` with your plan's actual token ceiling.** - **Verdict** = `go` when the active block is under the threshold, `no-go` at or over it, `unknown` when there is no usage data, no active block, or no ceiling to measure against. - **Exit code** = `0` go · `1` no-go · `2` unknown — so a dispatch script can gate on it directly. - On **no-go** it also reports `secondsUntilWindowClears` and a `min(3600, …)` poll interval, so you know how long until the window resets. ## How to use it 1. **Before a wave** (a fan-out of subagents, a `prime-sweep`, an orchestrated run), call `/budget-check`. 2. **GO** → launch the wave. 3. **NO-GO** → trim the wave (fewer concurrent workers), wait for the window to clear (the reported interval), or proceed deliberately — your call, surfaced not forced. 4. **UNKNOWN** → the gate cannot vouch; decide on other grounds and say so. A common, fixable cause is no inferable ceiling (a fresh environment with no historical block) — pass `--token-limit <N>` with your plan's real token budget to get a meaningful gate. This is a **runtime** tool — it reads *your* local usage logs, so it has nothing to measure in CI. The value is at the live pre-wave decision point, never in a pipeline. ## Boundary - Not `/ask-gate` — that triages a handler-facing *question*; budget-check gates a *spend*. - Not `/orchestrate-mode` or `/multi-agent-mode` — those *run* the wave; budget-check only decides whether it should start. - It encodes no policy and amends no directive: a skill you call, not a rule that fires. > **Human output.** This skill's handler-facing output obeys the human-output > contract (`human-output/SKILL.md`). > **Next skills.** On completion, run the Next Skills protocol: surface the front-matter recommendations for the caller to pick. Offer only — never auto-invoke. > **Self-improvement.** On completion, run the Self-Improvement Protocol: apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.