Skip to content
Skills Library
AI & agents · Analysis

usage-watcher

/usage-watcher

Reduce paid credit spend and rate-limit risk with deterministic usage analysis and budget guardrails. Use when planning high-volume agent work, reviewing recent burn, or setting lean/standard/surge operating caps.

Licence
MIT
Last repository change
28.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
1
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 28.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/usage_guard.py

What it does and when to use it

Reduce paid credit spend and rate-limit risk with deterministic usage analysis and budget guardrails. Use when planning high-volume agent work, reviewing recent burn, or setting lean/standard/surge operating caps.

Original author description

Reduce paid credit spend and rate-limit risk with deterministic usage analysis and budget guardrails. Use when planning high-volume agent work, reviewing recent burn, or setting lean/standard/surge operating caps.

How it works

  1. Workflow
  2. Analyze Command
  3. Budget Plan Command
  4. Mandatory Chain Gate
  5. Mode Selection Rubric
  6. Guardrail Policy
  7. Scope Boundary
  8. References
  9. Loopback
Original SKILL.md headings · 99 lines, 410 words
SKILL.md preview
---
name: usage-watcher
description: Reduce paid credit spend and rate-limit risk with deterministic usage analysis and budget guardrails. Use when planning high-volume agent work, reviewing recent burn, or setting lean/standard/surge operating caps.
---

# Usage Watcher

Use this skill to control usage cost and avoid rate-limit surprises.

## Workflow

1. Capture recent usage history to CSV/JSON.
2. Ingest live local-compute accounting from the running stack (`/health` plus `/api/accounting/summary`) whenever loopback evidence is available.
3. Run `usage_guard.py analyze` to measure burn rate, rate-limit posture, and local displacement value.
4. Run `usage_guard.py plan` to set practical daily/session caps.
5. Select and record a chain usage mode (`economy`, `standard`, `surge`) from the analysis and plan outputs.
6. Apply the recommendations before large agent workflows.

## Analyze Command

```bash
python3 "$CODEX_HOME/skills/usage-watcher/scripts/usage_guard.py" analyze \
  --input /path/to/usage.csv \
  --window-days 30 \
  --daily-budget 140 \
  --weekly-budget 900 \
  --credits-remaining 236 \
  --five-hour-limit-remaining 100 \
  --weekly-limit-remaining 0 \
  --stack-health-url http://127.0.0.1:9000/health \
  --stack-summary-url http://127.0.0.1:9000/api/accounting/summary \
  --json-out /tmp/usage-analysis.json \
  --format table
```

## Budget Plan Command

```bash
python3 "$CODEX_HOME/skills/usage-watcher/scripts/usage_guard.py" plan \
  --monthly-budget 2800 \
  --reserve-percent 20 \
  --work-days-per-week 5 \
  --sessions-per-day 3 \
  --burst-multiplier 1.5 \
  --json-out /tmp/usage-plan.json \
  --format table
```

## Mandatory Chain Gate

Before finalizing skill chains, provide:

- `usage_analysis_json=/tmp/usage-analysis.json`
- `usage_plan_json=/tmp/usage-plan.json`
- `usage_mode=<economy|standard|surge>`
- `stack_evidence` when a local loopback stack is available

If this evidence is missing, chain selection is incomplete and must fail closed.

## Mode Selection Rubric

Use deterministic mode selection from analysis output:

1. `economy`:
   - daily status is `red`, or
   - weekly status is `red`, or
   - projected 30-day burn exceeds remaining budget.
2. `standard`:
   - daily/weekly status are `green` or mixed `green/yellow`,
   - no active governor `throttle`/`disable` recommendation.
3. `surge`:
   - explicit deadline pressure is present,
   - budget remains within guardrails,
   - governor action is not `throttle`/`disable`.

Always record rationale in one short line with the selected mode.

## Guardrail Policy

- Economy mode for discovery and triage.
- Standard mode for normal implementation tasks.
- Surge mode only for urgent deadlines.
- Prefer bounded scripts and cached artifacts over repeated broad discovery.
- When preview displacement value is positive, prefer local-first routing and skill chains that preserve paid credits and included-usage headroom.
## Scope Boundary

Use this skill only for the `usage-watcher` lane and workflow defined in this file and its references.

Do not use this skill for unrelated lanes; route those through `$skill-hub` and the most specific matching skill.

## References

- `references/cost-control-playbook.md`
- `references/usage-csv-template.csv`

## Loopback

If this lane is unresolved, blocked, or ambiguous:

1. Capture current evidence and failure context.
2. Route back through `$skill-hub` for chain recalculation.
3. Resume only after the updated chain returns a deterministic next step.
Files in this package (5)
  • SKILL.md 3 KB
  • agents/openai.yaml 1 KB
  • references/cost-control-playbook.md 2 KB
  • references/usage-csv-template.csv 1 KB
  • scripts/usage_guard.py 21 KB

Versions

The database has no other skills named usage-watcher.

Database snapshot: 13.11.2026 · package version f3bd876b5a43 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ops-credit-burn-rate-watcher
    Use when monitoring token and cost consumption per tenant, user, or matter across all connected LLM providers. Tracks burn rate trends, alerts when a tenant is projected to hit their plan limit within 7 days, flags abnormal per-turn costs driven by inefficient model selection or…
  • 100hatch3r-cost-tracking
    Tracks token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
  • 100skill-cost-credit-governor
    Govern per-skill credit and token spend with deterministic warn/throttle/disable actions. Use when usage spikes, agent chatter, or budget overruns must be detected and contained.
  • 100tokenmeter
    Open the Tokenmeter dashboard, a local web page that tracks token usage, cost, rate-limit windows and cache misses for every prompt in Claude Code, Codex and Copilot CLI. Use when the user asks about token usage, token spend, cost per prompt or per commit, cache hit rate, usage…
  • 100lindy-cost-tuning
    Optimize Lindy AI costs through credit management, model selection, and agent consolidation. Use when reducing spend, analyzing credit usage patterns, or optimizing budget allocation across agents. Trigger with phrases like "lindy cost", "lindy billing", "reduce lindy spend",…
  • 95status
    Claude Code のサブスクリプション usage limit (5 時間セッション枠・週次枠の使用率と reset 時刻) を取得する。「rate limit」「残量」「usage limit」「5時間・週次枠の残りや使用率」を確認したいときに使う

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.