Skip to content

TOKEN-BUDGET.md

Latest commit

 

History

History
89 lines (66 loc) · 2.72 KB

TOKEN-BUDGET.md

File metadata and controls

89 lines (66 loc) · 2.72 KB

Token Budget

Skills load within a configurable token budget to avoid context bloat:

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
Overflow Queued Excess skills queue for next session

Installed vs Loading (v1.19+)

The budget system distinguishes between two dimensions:

Dimension Description
Installed Total Sum of all skill files on disk (everything available)
Loadable Total Skills that will actually load into context after tier-based selection

The Loading Projection simulates what the BudgetStage pipeline would select:

  1. Critical skills load first (always included if they fit)
  2. Standard skills load next (included if budget remains)
  3. Optional skills load last (included only if space allows)

Skills exceeding the single-skill character limit (default 15,000 chars) are flagged as oversized.

Per-Profile Budgets (v1.19+)

Different agent profiles can have different cumulative budgets:

{
  "token_budget": {
    "cumulative_char_budget": 15500,
    "profile_budgets": {
      "executor": 20000,
      "planner": 12000,
      "researcher": 8000
    }
  }
}

Priority chain: config profile_budgets > config cumulative_char_budget > env SLASH_COMMAND_TOOL_CHAR_BUDGET > default 15500.

CLI Status Display

Check current status:

skill-creator status

Output example (v1.19+):

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 budget

JSON output:

skill-creator status --json

Returns structured data with installed array and projection object.

Budget History (v1.19+)

Budget snapshots track both dimensions over time:

Field Description
installedTotal Total installed chars at snapshot time
loadedTotal Total loaded chars at snapshot time
skillCount Number of skills

The getDualTrend() function computes installedCharDelta and loadedCharDelta for trend analysis. Old snapshots without dual fields are automatically migrated.

Skills that cost more tokens than they save are flagged for review.