Loop Budget Guard
Check token budget and run-log spend before and after each loop run; enforce early exit when over budget or when there's no actionable work.
Evidence: The skill itself requests no extra permissions and no malicious behavior or data exfiltration is apparent. The repo includes SECURITY.md recommending least privilege and path denylists, and is MIT-licensed. However, the skill reads and may modify loop-budget.md and loop-run-log.md without clear user confirmation or rollback mechanisms; external effects (e.g., exiting loops) may impact automation but are not explicitly limited. Deduction for lack of explicit user confirmation and recovery.
Evidence: Instructions are relatively clear (read/write files at start/end), but no test suite or execution evidence is present. Repo has CI workflows and test scripts, but coverage for this skill is unknown. Static read cannot verify key paths, and handling of abnormal input (e.g., missing files or malformed data) is not described; failure feedback is unclear. Hence low reliability.
Evidence: The skill addresses a clear scenario (budget checking) and fits loop engineering. Trigger conditions (start and end) are semantically clear, audience (developers using AI coding agents) is defined. But capability boundaries and non-fit ranges are not declared, and no mention of mainland-China network reachability. Core function depends on local files, not overseas services, so environment fit is acceptable.
Evidence: Skill file is simple with description and steps, but lacks versioning, changelog, and maintenance responsibility. Repo has README and SECURITY, but the skill lacks examples, FAQ, and known limitations. No explicit version control or changelog. Deduction.
Evidence: Skill describes intended task (budget check, run log), but no sample outputs or verification of direct usability. Marginal value may be limited as users might monitor budgets manually. Static read cannot verify correctness. Hence low score.
Evidence: Repo has CI workflows (audit.yml) and test scripts, but no direct test evidence for this skill. Key claims (e.g., auto-exit) are not independently verified. Static read cannot reproduce. Hence low score.
- This skill may modify loop-budget.md and loop-run-log.md; ensure backups or version control before use.
- The skill does not describe handling for missing or malformed files; users must monitor for anomalies.
- Static review cannot verify actual behavior; test in a controlled environment before production use.
What does this skill do, and when should you use it?
This skill is designed to manage token budgets in AI coding agent loops. It runs at the start and end of every loop iteration, reading `loop-budget.md` for daily caps and kill-switch flags, and `loop-run-log.md` for recent entries. It sums token estimates for the active pattern and enforces thresholds: at 80% spend, it switches to report-only mode; at 90%, it yields to a budget-negotiation skill if high-priority items remain; at 100% or with a pause-all flag, it exits immediately. Additionally, it exits quickly when there's no actionable work. At the end of a run, it appends a JSON record with metrics like run duration, items found, actions taken, and token estimate. This skill prevents overspending and keeps loops efficient and auditable.
Reads loop-budget.md for daily caps and kill-switch flags; reads recent entries in loop-run-log.md (last 24h); sums tokens_estimate for the active pattern; decides based on spend thresholds whether to stay in normal mode, enter report-only mode, delegate to the budget-negotiator skill, or exit immediately; checks STATE.md for actionable items and exits in under 5k tokens if none; appends a JSON object to loop-run-log.md after each run with run_id, duration, items_found, actions_taken, escalations, tokens_estimate, and outcome; appends an alert to loop-budget.md when self-throttling.
- A developer running high-frequency loops (e.g., CI sweeper, PR babysitter) with Claude Code or Codex wants to avoid wasting tokens when there's nothing actionable and ensure fast exits.
- A team enforcing strict daily token budgets uses this skill to trigger different responses at 80% and 90% spend, preventing overspend.
- An engineer running multiple loop patterns wants to automatically log token consumption at each loop boundary for cost analysis.
- A user needs an emergency stop mechanism for automated loops, using the `loop-pause-all` flag or hitting 100% spend to exit immediately.
- A developer wants loop runs to be auditable, relying on the structured JSON log to record key metrics of each run.
What are this skill's strengths and limitations?
- Clear budget thresholds (80%, 90%, 100%) provide phased responses, preventing abrupt stops.
- Supports emergency stop via `loop-pause-all` flag.
- Forces quick exit (<5k tokens) when there's no actionable work, saving resources.
- Records structured JSON after each run for auditing and cost analysis.
- Integrates with other skills (e.g., budget-negotiator) for smarter budget handling.
- Requires the project to have `loop-budget.md`, `loop-run-log.md`, and `STATE.md`; without these files, the skill cannot function.
- Relies on token estimates which may differ from actual consumption, leading to imprecise budget control.
- Lacks an independent test suite, so reliability is unverified.
- The skill description is brief and does not detail the config file formats; users may need to consult repository docs.
How do you install this skill?
The skill resides in skills/loop-budget/ within the monorepo. To use it standalone, copy the folder into your Agent Skills directory (e.g., ~/.claude/skills/), or scaffold via npx @cobusgreyling/loop-init as described in the README. The README does not provide a standalone install command; follow the quickstart for the collection installation.
How do you use this skill?
Instruct your AI agent to run this skill at the start and end of each loop iteration. For example, prompt in Claude Code or Codex: "Run the loop-budget skill to check the budget before starting the loop and log the run when finished." The skill will automatically read budget files, calculate spend, decide whether to enter report-only mode or exit, and append a JSON record.
How does this skill compare with similar options?
It works in concert with the budget-negotiator skill from the same repository: at 90% spend with high-priority tasks, this skill defers to the negotiator. The repository does not provide other direct competitors.