Claude Skill

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download allemaar-open-skills-skills_budget-check-acf5f79.zip · 7 KB

Install

skills CLI npx skills add https://github.com/allemaar/open-skills/tree/main/skills/budget-check
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
Git 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 @STAMP date.

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 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.

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.

No comments yet.

Reviews (0)

No reviews yet.