​

Token economics: the why of skill constraints

​

The four budgets

​

1. The auto-compaction budget (25,000 tokens shared, 5,000-token per-skill survival floor)

• A 500-line SKILL.md is approximately 5,000 tokens (the rule of thumb is ~10 tokens per line for prose; tighter prose runs lower, code-heavy prose runs higher).
• A 500-line skill survives compaction. A 1,000-line skill is truncated to its first half after compaction. The truncated half is the part the agent will not see.
• “Most-recently-invoked first” means the skill you invoked at minute 5 of a 4-hour session may be dropped after compaction; the skill invoked at minute 230 stays.

​

2. The description listing budget

​

3. The per-skill model: and effort: overrides

• model: per-skill model override. Example: a skill that needs Opus reasoning can declare model: opus in its frontmatter (an alias, so the example does not pin a dated model ID). The harness applies the override for the rest of the turn the skill is active.
• effort: per-skill reasoning level. Example: effort: high for a deep-thinking skill.
• Default: inherit (use the parent’s model and effort).

​

4. Session-start injection: full body or pointer

• Full body. The using-superpowers hook reads the SKILL.md, escapes it for JSON and emits it as hookSpecificOutput.additionalContext. obra/superpowers#1220 measured 1,370 tokens per firing and about 17,800 tokens over 57 hours and 13 firings in two sessions; its matcher includes compact, so it re-fires after every compaction.
• Pointer. A short note that names the skill and the actions it governs, and tells the agent to load it and read the procedure its routing table links. The AgentsMD pointer was 417 characters (about 105 tokens), later widened to 482 characters to cover every new kind of action (routing case study).

​

The calculator

• S = SKILL.md size in lines.
• D = description + when_to_use combined character count.
• F = expected per-session firing rate (typical: 0-3).
• M = loading mechanism: description-triggered (default), session-start pointer, or full body injected at session start.
• P = pointer size in tokens (the AgentsMD pointer is about 105).
• N = number of other concurrently-active skills the agent may have loaded.

footprint_tokens = S × 10           # ~10 tokens per line of prose

if M == "full-body-hook":
    cost_tokens = footprint_tokens                  # full body, every session
elif M == "pointer":
    cost_tokens = 100 + P + (footprint_tokens if fired else 0)
                  # description + pointer every session; body when loaded
elif M == "description-triggered":
    cost_tokens = (100 if not_fired else footprint_tokens)
                  # ~100 for description; full body on activation
                  # so per-session: ~100 + (F * 0 if already-activated)
                  # First fire loads body; subsequent fires reuse the loaded body

if footprint_tokens > 5000:
    after_compaction = "first 5000 tokens only"
else:
    after_compaction = "full body retained"

total_active_token_budget = 25000
your_share = footprint_tokens
remaining_for_others = total_active_token_budget - your_share
how_many_others_at_5k_each = remaining_for_others / 5000

​

Worked example: karpathy-wiki

• S = 476 lines (REVIEWER verification: 476 not 455, post v2.2).
• footprint_tokens ≈ 4,800 (just under the 5,000 floor).
• D ≈ 750 chars (description only; no when_to_use). Well under the 1,024 spec cap and the 1,536 listing cap.
• F ≈ 1-3 captures per typical session.
• M = description-triggered. No SessionStart-hook injection.
• Per-session cost when not fired: ~100 tokens (description in listing).
• Per-session cost on first fire: ~4,900 tokens (description + body).
• Subsequent fires same session: 0 (body already loaded).
• Concurrent-skills room: ~20,000 remaining tokens, ~4 other skills at 5,000 tokens each before compaction.

​

Design choices the numbers force

• Push detail into references/. The agent reads SKILL.md by default; references load only when the agent decides to read them (or when SKILL.md links to one inline). Heavy reference material (API docs, comprehensive syntax) belongs there. The agent-skills spec rule: file references one level deep from SKILL.md, no nested chains.
• Front-load triggers in the description. The 1,536-char listing truncation makes the bottom of long descriptions invisible.
• Pick description-triggered loading as the default; add a pointer for moments. A pointer of about 105 tokens made a moment-shaped skill load where its description did not. Full-body injection costs the whole body every session and after each compaction.
• Use model: and effort: overrides surgically. A skill that demands Opus declares it; the user does not need to switch. (Claude Code only; cross-platform skills should not assume this works elsewhere.)
• Audit your SKILL.md size at every ship. wc -l SKILL.md is the cheapest gate. If it is over 500, the next ship’s plan should include a “split to references” task.

​

When the numbers do not apply

• The 25,000 / 5,000 re-attach rule is Claude Code’s. This repo’s Codex and Gemini CLI pages record no equivalent; check the host you target. Gemini CLI supports Agent Skills natively (descriptions always listed, bodies on activation), and GEMINI.md is always-on context like CLAUDE.md.
• The 25,000 / 5,000 numbers match the Claude Code docs as re-read on 2026-09-29. They will change. Re-fetch when shipping.
• Fork-mode skills (context: fork + agent) do not pay the parent context’s compaction tax; the fork has its own context. This is the cost-saving rationale for forking; see Mental model and REVIEWER M3.

​

Sources

• REVIEWER G2 (the 25k auto-compaction budget; the 5k per-skill survival floor; 500 lines ≈ 5,000 tokens); re-checked against the Claude Code Skills docs on 2026-09-29.
• REVIEWER G7 (per-skill model: and effort: overrides).
• Per-host listing and hook-output limits: Claude Code, Codex, Grok Build and OpenCode, each checked 2026-09-29 against the primary sources they cite.
• obra/superpowers#1220 (full-body injection cost; first recorded in LANDSCAPE 2.1).
• Routing case study and the #174 records (pointer size, per-host results, mean tokens per run).
• LANDSCAPE 1.3 (Anthropic Claude Code docs lifecycle; auto-compaction behavior).