Writing Skills That Load Context on Demand, Not by Default

There's an instinct, when building out a library of agent skills, to treat it like documentation: write everything down, make it comprehensive, and trust that a thorough reference is better than a sparse one. That instinct is correct for documentation a human reads at their own pace, skimming for the relevant section. It's wrong for a skill library an LLM has to carry in context, because unlike a human skimming a page, a model pays a real cost for every skill description sitting in its context window whether or not that skill gets used this turn.

The pattern that resolves this — and the reason SKILL.md-style progressive disclosure has become the default shape for agent skill libraries in 2025 and 2026 — is loading skills on demand instead of by default. The model always sees a lightweight index: one line per skill, just enough to know it exists and roughly what it's for. The full instructions, examples, and reference material for a given skill only enter context when that specific skill actually gets invoked.

Why "load everything" doesn't scale

A skill library built the documentation way — full instructions for every skill, always present in context — has a cost that scales linearly with library size. Five detailed skills might be a manageable few thousand tokens of standing overhead. Fifty detailed skills is an unmanageable standing tax, present on every single call the agent makes, whether the task at hand touches one of those fifty skills or none of them.

This is the same attention-budget mechanic that governs tool count, applied to a category of context that in principle should scale better than tools do, because skills are pure information rather than live-system capabilities — and yet naive skill libraries hit the same wall for the same reason: every entry that's fully loaded, always, is competing for attention on every call regardless of relevance. A skill library that grows without a loading discipline doesn't just get slower to maintain. It actively degrades the agent's performance on tasks that have nothing to do with most of the skills sitting in context.

What progressive disclosure actually looks like

The fix is a two-tier structure. Tier one, always present: a compact catalog — skill name plus a one-line description, ideally specific enough that the model can judge relevance without needing to open the full skill. Tier two, loaded conditionally: the full skill content — detailed instructions, examples, edge cases, sometimes reference files — which only enters context once the model has determined, from the tier-one description, that this particular skill applies to the task at hand.

This means a skill library with two hundred entries can cost the model roughly the same per-call overhead as a library with twenty, as long as the always-loaded tier stays to one line each. The two-hundred-entry version only becomes expensive on the calls where many skills genuinely need to be considered and loaded simultaneously — which, if the library is well-organized by task type, should be rare. Scale lives in the index, not in the standing cost.

The one-line description is doing the real work

Because the tier-one description is the only thing the model sees before deciding whether to load a skill, its quality determines whether the whole system functions. A vague description — "handles data tasks" — gives the model nothing to disambiguate on, which recreates exactly the tool-overlap problem that degrades toolset accuracy: several similar-sounding entries, no clear signal for which one actually applies, and a model guessing. A specific description — "converts a CSV export into the internal ledger format used by the finance team's monthly close" — lets the model make a confident relevance judgment from one line, without ever paying the cost of loading the full skill to find out it wasn't the right one.

Writing a good one-line skill description is a genuinely different skill from writing good skill instructions, and it's the one most teams under-invest in, because it's easy to treat the index as a formality and put the real effort into the content it points to. In a progressive-disclosure system, the index carries more of the functional weight than its length suggests — it's the only part of the skill that's always being evaluated.

What belongs in the loaded tier, and what doesn't

Not everything inside a skill needs equal weight once it's loaded, either. The core instructions — what the skill does, how to do it, the key constraints — should load immediately when the skill is invoked. Bulkier reference material — a full API specification, a long list of examples, background documentation — is often better structured as a further layer the agent can pull from only if the specific task requires that level of detail, rather than dumping the entire reference into context the moment the skill is touched at all.

This nested structure — index, then core instructions, then deep reference — mirrors the same principle at every layer: nothing loads until something upstream has established that it's actually needed. A skill that's invoked for a simple case shouldn't pay the context cost of reference material meant for the complex case, any more than an unrelated skill should pay the cost of being loaded at all.

Search versus browsing, at the index layer

There's a second-order question that only shows up once a skill library gets large enough: how does the model actually find the right entry among the index? Below a few dozen skills, presenting the full one-line index up front works fine — the model can scan the whole list in the same way a person skims a table of contents. Past that point, the index itself starts to compete for the same attention budget it was designed to protect, which pushes teams toward a further layer: a search or matching step over the index rather than presenting all of it every time, so the model sees only the handful of catalog entries plausibly relevant to the current request, not the full list of two hundred.

This is the same progressive-disclosure principle applied one level up — even the lightweight index isn't exempt from the budget discipline once it grows large enough, and a library that scaled well from five skills to fifty can hit a second wall at five hundred if the index itself was never designed to be searched rather than simply read in full.

The discipline is maintenance, not just initial design

The trap with progressive disclosure is that it's easy to get right on day one and let drift on day fifty. A skill written carefully with a tight one-line description gets edited six months later — someone adds a paragraph of new instructions, a new example, a caveat for an edge case that came up once — and none of those additions touch the index line, so nobody re-evaluates whether the description is still accurate or whether the skill has quietly grown large enough that its always-loaded footprint (the index entry) versus its loaded-on-demand footprint (everything else) is still the right split.

The maintenance habit that keeps this working is treating the index line as a contract, not a formality: every time a skill's actual content changes meaningfully, the one line that decides whether the model ever sees that content should get revisited too. A skill library is only as cheap as its index is accurate — and an index that's stopped matching what's behind it doesn't just mislead the model occasionally, it undermines the entire premise that made a large skill library affordable to carry in the first place.

Part of the "Context Engineering" series on aiskill.market.