Structured Data
Capability Metadata
| Field | Value |
|---|---|
| ID | CAP-004 |
| Version | v1.0 |
| Domain | Core Learning |
| Status | Documented |
| Related | CAP-001, CAP-003, CAP-016, CAP-017 |
| Budget | 2-5% of context window |
| Pipeline | 6-stage loading (Score → Resolve → ModelFilter → CacheOrder → Budget → Load) |
Configuration Reference
Toggle: auto_load in integration.json
{
"auto_load": true,
"token_budget_percent": 3,
"budget_hard_limit": true
}Budget: 2-5% of context window (configurable, hard limit enforced)
Trigger: automatic at session start; also triggered by /sc:status
Technical Specifications
6-Stage Pipeline (v1.8+):
// 6-stage skill loading pipeline (CAP-016)
Stage 1: Score — relevance scoring against current context
Stage 2: Resolve — project-level overrides user-level
Stage 3: ModelFilter — filter by compatible model profile
Stage 4: CacheOrder — sort by cache-friendly ordering (CAP-019)
Stage 5: Budget — enforce token budget (2-5% hard limit)
Stage 6: Load — inject into context; queue overflow
// Skills that exceed the budget are queued and noted:
interface LoadResult {
loaded: Skill[];
deferred: Skill[]; // exceeds budget
budget_used: number; // tokens consumed
budget_limit: number;
}Original (v1.0): load all skills up to a count limit (no scoring)
Overview
Auto-Loading is the bridge between the skill library and live Claude sessions. When a new context starts, the auto-loader scans the skill library, scores each skill for relevance to the current task, and loads the highest-scoring skills within the 2-5% token budget. Skills that don't fit are queued and noted. The user never manually manages what's loaded — relevance and budget are handled automatically.
The token budget constraint (2-5% of context window) exists because loading skills has a cost. Context devoted to skills is context unavailable for code, conversation, and thinking. The 2-5% range is the empirically derived sweet spot: enough to load the most relevant skills, small enough to preserve useful working context. Skills that exceed the budget are listed in the session header so you know what was deferred and can manually invoke them if needed.
Relevance scoring uses the skill's declared trigger keywords matched against the current session context — the files open, the recent commands, the user's request text. A skill triggered by "test" and "commit" scores higher when the user mentions running tests before committing than when they ask about database migrations. This context-sensitivity is what makes auto-loading useful rather than simply loading everything every time.
History
Auto-Loading was part of the v1.0 core, but it has evolved dramatically. The original v1.0 loading was simple: load all skills up to a count limit. There was no relevance scoring, no token budget enforcement, no stage pipeline. If you had 10 skills and the limit was 8, the first 8 alphabetically got loaded. This worked when skill libraries were small; it broke down as libraries grew.
In v1.8, the loading mechanism was completely replaced by the 6-stage pipeline architecture introduced by the Skill Loading Pipeline (CAP-016). Relevance scoring replaced count limits. Per-agent token budgets (CAP-017) replaced global limits. Cache-aware ordering (CAP-019) optimized prompt cache hit rates. The "load what fits" heuristic became a sophisticated resource allocation system. The external interface remained the same — skills load automatically at session start — but the internal implementation is now a full pipeline with six distinct stages, each with its own rules and configuration.
Key Concepts
Think of it like a chef who sets out only the tools needed for tonight's recipe, not every tool in the kitchen. Before starting, the chef looks at what's on the menu and picks out a knife, a whisk, and a saucepan — not the pasta pot, the wok, and the bread knife, because those aren't needed tonight.
Auto-Loading does the same thing with skills. Before your Claude session starts, it looks at what you seem to be working on and loads only the most relevant skills — the ones most likely to help. If it can't fit everything in the available space (the token budget), it sets the lower-priority tools aside and tells you what was left out.
The 2-5% budget isn't arbitrary — it's the difference between a well-prepared workspace and a cluttered countertop. Too many tools out at once means you can't find what you need. The budget keeps Claude's context focused on the current work.
Usage Examples
Example 1: Check what skills are loaded
# Inside a Claude Code session
/sc:status
# Output:
# Loaded skills (2,847 tokens / 3% budget):
# - beautiful-commits [score: 0.92] — triggers: commit, git
# - cap-page-template [score: 0.88] — triggers: capability, CAP
#
# Deferred (budget exceeded):
# - code-review [score: 0.61] — triggers: review, PR
# - test-runner [score: 0.45] — triggers: test, jestExample 2: Configure budget percentage
// integration.json — increase budget for skill-heavy workflows
{
"auto_load": true,
"token_budget_percent": 5, // use up to 5% of context
"budget_hard_limit": true // never exceed this limit
}Example 3: Understand deferral notices
# When a skill is deferred, Claude notes it at session start:
# "Skill 'code-review' deferred (budget: 3% / 94,000 tokens used).
# Mention 'code review' to load it on demand."
# You can ask Claude to load a deferred skill:
# "Load the code-review skill for this session."