Skills: Index in Context, Body on Demand

See why skill descriptions stay in context while full bodies load only when the model selects one.

Read this as What does the model see before it chooses a skill?
Failure Trap
Eager-loading every skill body and burying the relevant instruction in irrelevant context.
Decision Rule
Keep descriptions on the shelf, open exactly one body on demand, and let unused bodies drop out.
Skills: Index in Context, Body on Demand See why skill descriptions stay in context while full bodies load only when the model selects one. Description shelf Description shelf names one paragraph always visible index Match Match task verb skill name clear scope retrieve Open drawer Open drawer one body on demand focused rules load Drop rest Drop rest closed drawers headroom less noise working set Eager trap Eager trap 10 bodies ~35K tokens 29% run too much Lazy path Lazy path descriptions + one body 95% run ~5.5K
1 / ?

The model sees a shelf of descriptions

Progressive disclosure starts with short skill descriptions in context, not full instruction bodies.

  • The description is the public API.
  • The body stays on disk.
  • The candidate set stays small enough to scan.

The task matches one description

The model chooses a skill by reading descriptions that name the action, input, and boundary.

  • Good descriptions are verb-first.
  • Examples disambiguate adjacent skills.
  • Generic descriptions are invisible.

Only the chosen body opens

After selection, the harness loads the full skill body into the working context.

  • The body can be detailed.
  • It arrives only when useful.
  • The harness owns the gate.

Unused bodies drop out

Other skill bodies remain out of context, preserving headroom for the actual task and files.

  • The catalog can be large.
  • The working set stays small.
  • Capability no longer equals always-on tokens.

Eager loading pays the 35K trap

The source example uses ten skills with bodies around 3,500 tokens each: eager loading spends about 35K tokens immediately.

  • Irrelevant bodies still tax attention.
  • The right instruction is harder to find.
  • The cited eager run scored 29 percent.

Lazy loading keeps the shelf cheap

Descriptions plus one opened body in the source example consume about 5.5K tokens and preserve the path to the 95 percent run.

  • Same model.
  • Same instructions.
  • Only retrieval architecture changed.