≡
Analysis & Verification
budget
Every skill you load into an agent consumes context window tokens. Budget tells you exactly how many, finds redundancy between skills, estimates costs across model pricing tiers, and tracks changes over time.
Why it matters
Context windows are finite and expensive. Loading 5 verbose skills at 10K tokens each consumes half of Claude's context window before the user even types a prompt. Budget helps you optimize: trim bloated skills, deduplicate overlapping content, and set token ceilings that CI enforces.
What it does
- Counts tokens per skill using cl100k_base encoding (within 5% across model families)
- Breaks down token usage per section within each skill
- Detects inter-skill redundancy via 4-gram Jaccard similarity
- Estimates cost across model pricing tiers (Haiku, Sonnet, Opus)
- Saves snapshots and compares against baselines to track budget changes over time
- Enforces token ceilings — exit 1 if total exceeds a configurable threshold
Usage
npx skills-check budget [dir] [options]Options
| Flag | Description |
|---|---|
-s, --skill <name> | Analyze a specific skill |
-d, --detailed | Per-section token breakdown |
--max-tokens <n> | Token ceiling — exit 1 if exceeded |
--save <path> | Save snapshot for future comparison |
--compare <path> | Compare against a saved snapshot |
--model <name> | Pricing model for cost estimates |
-f, --format <type> | Output: terminal or json |
Examples
Analyze all skills
npx skills-check budgetDetailed breakdown
npx skills-check budget --detailedEnforce a ceiling
npx skills-check budget --max-tokens 50000Save baseline
npx skills-check budget --save baseline.jsonCompare to baseline
npx skills-check budget --compare baseline.jsonCI tip
Set --max-tokens in CI to prevent skill bloat. Save a baseline in main and use --compare on PRs to catch token regressions before they merge.