Progressive Loading

Discovery Was Tier One

The previous lesson covered where an agent finds skills. This lesson covers what happens once it has found them — the full three-tier loading model that makes it possible for an agent to have dozens of skills installed without paying for all of them at once.

You already saw tier 1 in the discovery lesson and tiers 2-3 in the hands-on walkthrough, in passing. This lesson makes the model explicit, because understanding it precisely is what lets you write skills that scale instead of skills that quietly bloat every conversation.

Tier 1: Catalog

At session start, every discovered skill contributes its name and description to what the agent holds in context — nothing else. This is a flat, small cost per skill, and it’s paid regardless of whether that skill is ever used in the session. An agent with 30 installed skills pays roughly 30 x 50-100 tokens for the catalog alone, whether the conversation touches one of them or none.

This is the tier that makes “install many skills, use only the relevant ones” a workable strategy rather than a context-budget problem.

Tier 2: Instructions

When a user’s request matches a skill’s description, the agent reads the entire SKILL.md body into context — not a summary, not a partial read. This is why the specification recommends keeping the body under 5,000 tokens: it’s the amount that loads in one shot, every single time that skill activates, for as long as it stays relevant to the conversation.

There’s no way to load “half” of SKILL.md — the body is one unit. If a skill’s instructions genuinely need more material than that, the answer isn’t a longer body; it’s tier 3.

Tier 3: Resources

Files in scripts/, references/, and assets/ load only when the body specifically points the agent to them — and only those files, not the whole folder. A skill can bundle a large reference manual, and none of it enters context unless a task actually needs that specific section.

This only works, though, if the body actually tells the agent when to reach for a given file. Compare:

<!-- Weak — gives the agent no signal about when this file matters -->
See references/ for more details.

<!-- Strong — a concrete trigger condition -->
If the API returns a non-200 status code, read references/api-errors.md
before proceeding.

The first version technically makes the reference file discoverable, but the agent has no way to know whether the current task needs it — so it either gets ignored or gets loaded speculatively, defeating the purpose. The second version only pulls the file in when the stated condition is actually true.

Why This Matters at Scale

Picture an agent with 40 skills installed, in a conversation about one narrow task. Without progressive loading, “having 40 skills available” would mean holding 40 full instruction sets in context at once — most of them irrelevant to anything being discussed. With it, that same agent pays the tier-1 catalog cost for all 40, and the tier-2 instruction cost for maybe one or two that actually matched the request. The other 38 stay at their ~100-token catalog entry and never cost more than that.

This is the entire reason skills can be a library an agent draws from, rather than a fixed cost baked into every conversation the way a system prompt is.

Predicting What Loads

Given a skill like this:

invoice-processing/
├── SKILL.md              # ~2,000 tokens
├── scripts/
│   └── validate.py         # loaded only if the body says to run it
└── references/
    ├── tax-rules-us.md      # loaded only if the body says "for US invoices, read this"
    └── tax-rules-eu.md      # loaded only if the body says "for EU invoices, read this"

For a session that never mentions invoices: tier 1 only — roughly 100 tokens, for the catalog entry.

For a session that asks about a US invoice: tier 1, plus tier 2 (the ~2,000-token body), plus — if the body’s instructions say to — tax-rules-us.md from tier 3. tax-rules-eu.md never loads, because nothing in the conversation ever pointed to it.

That’s the whole model. Getting it right when you write a skill — in the next lesson, Files & Resources — mostly comes down to one habit: state the trigger condition for every file you bundle, the same way tax-rules-us.md above is gated on “for US invoices.”

Summary

• Tier 1 (catalog: name + description) loads for every skill at session start, at a small, flat cost per skill
• Tier 2 (the full SKILL.md body) loads only when a skill activates, and loads as one complete unit
• Tier 3 (scripts, references, assets) loads only when the body explicitly points to a specific file — never automatically, never as a whole folder
• This is what lets an agent hold many skills without a proportional context cost: most installed skills never advance past tier 1 in any given conversation

You now understand what an agent does with a skill once it’s found it. Next, you’ll build one that actually uses all three tiers — bundling real scripts, references, and assets alongside SKILL.md.