Progressive disclosure
Write a scoped skill package and manage its instructions and references within a task's context budget.
THE IDEA
Progressive disclosure
Skills are loaded in stages. At startup the agent reads only each skill's name and description (about 100 tokens). When a task matches, it loads the full SKILL.md (the specification recommends under 5,000 tokens and under 500 lines). Files in scripts/, references/ and assets/ are read only if the task needs them. With 20 skills that is 2,000 tokens at startup instead of 82,000 if every body were always loaded.
Load metadata for discovery, the instructions when the skill is needed, and resources only when the task requires them. Keep SKILL.md short and put detail in separate files one level deep.
Predict first. Does installing a skill imply its entire reference library must always occupy context?
Chapter context
A skill packages reusable task instructions and optional supporting material. Context engineering decides which instructions and evidence are available for a particular operation. Loading more text is not automatically better than selecting the right text.
TRY IT YOURSELF
Part 1. Do it hands-on
Cost the three stages by hand, then write the cost model and a simple skill selector.
Load metadata for discovery, the instructions when the skill is needed, and resources only when the task requires them. Keep SKILL.md short and put detail in separate files one level deep.
- To do: Twenty skills are installed. At startup only each skill's metadata (name and description, about 100 tokens) is loaded. Tokens at startup?
- To do: A task activates one skill whose body is 4000 tokens. Tokens now in context from skills?
- To do: If every skill's body were loaded for every task instead (20 × (100 + 4000))?
- To do: Does installing a skill imply its entire reference library must always occupy context? Type yes or no
Part 2. Do it in code
- A skills dict maps a skill name to {"description": str, "meta": int tokens, "body": int tokens, "refs": {file: tokens}}.
- startup_cost(skills): the sum of every skill's meta tokens (all skills are discovered at startup).
- context_cost(skills, activated, loaded=None): startup cost plus the body tokens of each activated skill plus the tokens of the reference files listed in loaded (a dict skill → list of files; only for activated skills; unknown files raise KeyError).
- eager_cost(skills): the cost if every skill's meta, body and ALL references were always loaded.
- savings(skills, activated, loaded=None): eager_cost minus context_cost.
- select_skills(task, skills): the sorted names of skills whose description shares at least one word of 4+ letters (case-insensitive, letters only) with the task.
Stuck, or something not working? You can come back to it any time.
CHECK YOUR UNDERSTANDING
Does installing a skill imply its entire reference library must always occupy context?
Chapter reference: math, worked example & code
This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.
Math and notation
For a synthetic combined budget W, a bookkeeping model is available = W − instructions − history − tool results − reserved output. Actual provider contracts can separate these limits, so use the chosen model's documented accounting when implementing.
Worked example
A synthetic 8192-token budget reserves 1200 for instructions, 2800 for history, 1600 for tool results and 1500 for output. Remaining space is 1092 tokens. A 900-token skill body fits under this model; adding a 2000-token reference does not. The remedy is to select or retrieve the relevant passage rather than silently dropping task constraints.
Reference code
The following example uses the Python standard library and does not call a remote service.
window=8192
used=1200+2800+1600+1500
remaining=window-used
assert remaining == 1092
assert 900 <= remaining
assert 2000 > remaining
Python examples are provided for study and local execution; this page does not execute Python.
Common mistakes
Compaction can lose evidence and constraints. Skill installation is not task authorization. A context limit and a product's memory feature are different mechanisms.