| Guide ID | UG-3 |
|---|---|
| Audience | Developers, Power users |
| Prerequisites | GS-2 (Core Concepts) |
| Time | 10 minutes |
| Difficulty | Intermediate |
Token Budget Management
Skills load within a configurable token budget to prevent context window bloat. The budget system controls which skills load, in what order, and how much total context they consume. This guide explains the budget mechanics, monitoring commands, and configuration options.
Budget Overview
The token budget reserves 2-5% of Claude Code’s context window for skills. Skills are loaded based on priority, with recently used skills cached and overflow skills queued for the next session.
| Setting | Default | Description |
|---|---|---|
| Budget | 2-5% | Percentage of context window reserved for skills |
| Priority | Specificity | More specific/relevant skills load first |
| Caching | Enabled | Recently used skills stay loaded across sessions |
| Overflow | Queued | Excess skills are queued for the next session |
| Single-skill limit | 15,000 chars | Maximum size for any individual skill |
| Cumulative limit | 15,500 chars | Default total budget for all loaded skills |
Installed vs Loading
The budget system distinguishes between two dimensions. Understanding this distinction is key to managing your skills effectively.
| Dimension | Description | What It Means |
|---|---|---|
| Installed Total | Sum of all skill files on disk | Everything available — may exceed budget |
| Loadable Total | Skills that actually load into context | After tier-based selection within budget |
You can have many skills installed (50,000+ chars total on disk) while only loading a subset into each session (staying within the 15,500 char budget). The loading projection simulates what the BudgetStage pipeline would select.
Loading Projection: Tier Selection
When loading skills, the budget pipeline selects them in tier order. Each tier is fully loaded before moving to the next, and loading stops when the budget is exhausted.
| Tier | Priority | Loading Behavior |
|---|---|---|
| Critical | 1 (highest) | Always included if they fit within budget |
| Standard | 2 | Included if budget remains after critical skills |
| Optional | 3 (lowest) | Included only if space allows after standard skills |
Within each tier, skills are further ranked by relevance to the current context, recency of activation, and specificity of their descriptions.
Per-Profile Budgets
Different agent profiles can have different cumulative budgets. This allows executor agents (which need more skill context) to load more skills than researchers or planners.
{
"token_budget": {
"cumulative_char_budget": 15500,
"profile_budgets": {
"executor": 20000,
"planner": 12000,
"researcher": 8000
}
}
}| Profile | Budget | Typical Use |
|---|---|---|
executor | 20,000 chars | Phase execution with many skills needed |
planner | 12,000 chars | Planning phases with moderate skill needs |
researcher | 8,000 chars | Research phases with minimal skill loading |
Profile names strip the gsd- prefix for lookup. A request for profile gsd-executor looks up executor in the map. See Configuration Guide for how to set these values.
Priority Chain
The system determines the effective budget by checking these sources in priority order. The first match wins.
| Priority | Source | Location |
|---|---|---|
| 1 (highest) | profile_budgets.<profile> | Integration config (.planning/skill-creator.json) |
| 2 | cumulative_char_budget | Integration config (.planning/skill-creator.json) |
| 3 | SLASH_COMMAND_TOOL_CHAR_BUDGET | Environment variable |
| 4 (fallback) | Default: 15,500 | Built-in |
CLI Status Display
Use skill-creator status to see current skill loading with a visual progress bar and loading projection.
skill-creator statusExample output:
Installed Skills (14):
typescript-patterns ████████░░ 27% 4,200 chars
react-hooks ██████░░░░ 20% 3,100 chars
git-workflow ███░░░░░░░ 10% 1,500 chars
...
Loading Projection (gsd-executor):
[████████████░░░░░░░░] 62% of budget
Loaded: 8 skills (9,600 chars)
Deferred: 6 skills (5,700 chars)
3 of 14 skills fit within budgetUse skill-creator budget for a detailed per-skill character breakdown with severity indicators.
skill-creator budgetExample output:
Character Budget
[████████████░░░░░░░░] 62% (9,300 / 15,500 chars)
Per-Skill Breakdown
(sorted by size, largest first)
[████░░░░░░] typescript-patterns
4,200 chars (27% of budget)
desc: 150, body: 4,050
[███░░░░░░░] react-hooks
3,100 chars (20% of budget)
desc: 120, body: 2,980Both commands support --json output for scripting. Use skill-creator status --json for structured data with installed array and projection object.
Budget History
Budget snapshots track both installed and loaded dimensions over time, enabling trend analysis.
| Field | Type | Description |
|---|---|---|
installedTotal | number | Total installed chars at snapshot time |
loadedTotal | number | Total loaded chars at snapshot time |
skillCount | number | Number of skills |
timestamp | string | ISO timestamp of the snapshot |
totalChars | number | Legacy field (still written for compatibility) |
The getDualTrend() function computes installedCharDelta and loadedCharDelta for trend analysis. Old snapshots without dual fields are automatically migrated on read, defaulting both values to totalChars.
Oversized Skills
Individual skills exceeding the single-skill character limit (default: 15,000 chars) are flagged as oversized. Oversized skills may be silently hidden by Claude Code even if they fit within the cumulative budget.
The skill-creator budget command shows severity indicators when skills approach or exceed the per-skill limit, along with actionable suggestions for reducing size.
Skills that cost more tokens than they save are also flagged for review. This can happen when a skill’s content is mostly generic advice that Claude would provide anyway.
Practical Tips
| Tip | Detail |
|---|---|
| Keep descriptions concise | Descriptions under 150 characters score better for activation and consume less budget |
| Use tiers strategically | Mark workflow-critical skills as Critical tier; mark experimental ones as Optional |
| Monitor regularly | Run skill-creator budget periodically to spot budget creep |
| Set profile budgets | Give executor profiles more budget; reduce budgets for lightweight profiles |
| Watch for oversized skills | Break large skills (>15K chars) into focused sub-skills |
| Review deferred skills | Check which skills are deferred in status output — they may need tier promotion |
Use --json for tracking | Script budget checks with skill-creator status --json and budget --json |
What’s Next
- Configuration Guide — Set budget values, profile budgets, and integration options
- Command Reference — Detailed docs for
status,budget, and all CLI commands - Skill Workflows — End-to-end workflows that incorporate budget management