Progressive disclosure

Read these first

• Agent skills
• Context engineering — selection

What you will know

• Trace a skill request and verify which metadata, body, and bundled files enter context at each step

  Descriptions can trigger false matches, while omitted prerequisites and examples can leave an otherwise valid skill unusable.

• Calculate the resting token cost of a library of skills

  At 1,000 skills with 20 metadata tokens each, the baseline is 20,000 tokens before any body is fetched.

• Structure a skill so its body loads only when relevant

  Put routing cues in metadata and keep prerequisites, examples, and large schemas behind a deliberate fetch boundary; otherwise relevance cannot be decided cheaply.

• Reference a file that is read only when needed

  A broken path or implicit dependency turns successful selection into a runtime failure, so test the lookup from a clean environment.

• Measure how deferred loading changes prompt tokens, latency, and task success against loading every skill body upfront

  The comparison exposes cases where saved context is outweighed by an extra fetch or where a missing body causes silent quality loss.

Chapters

1. 1

   Metadata always, body on selection, files on request

   The disclosure boundary has three tiers, and knowing which one a piece of text sits in tells you when the model can see it. Trace a single request: which name-and-description pairs are resident, which body arrives after selection, which bundled file is read only when the body asks. A skill can be perfectly written and still unusable because a needed prerequisite sat one tier too far out.

   Read chapter
2. 2

   Twenty thousand resting tokens before a single body loads

   A thousand skills at twenty metadata tokens each cost 20,000 tokens on every request, whatever is 'only loaded when relevant'. The bill is the smaller half: the model must now discriminate among a thousand near-neighbour descriptions, and its failure mode is a wrong or absent selection that reads as a mediocre answer rather than a cost line. Learn to compute the resting cost and to name the number where you stop adding.

   Read chapter
3. 3

   Past that number the library needs routing, not fewer capabilities

   A platform team with 400 real capabilities cannot answer the resting-cost problem by stopping, so the architecture has to change rather than the catalogue. Retrieve the top-k descriptions per request and you have reintroduced a retrieval system with its own recall failures; scope the visible set per agent, product surface or user role and no single request ever weighs 400 candidates; group skills behind a coarse router so the model discriminates in two cheap steps instead of one expensive one; or merge near-neighbours whose descriptions were competing for the same requests anyway. Each option buys resting tokens back and hands you a new failure to watch for.

   Read chapter
4. 4

   Routing cues in the description, action-changing steps in the body

   Deciding what goes where has one criterion, and it is not length. Put the triggering situations and the words real requests use into the description; keep the steps that change what the agent does in the body; move prerequisites, long examples and large schemas into bundled files. A size cap will happily defer a schema the agent cannot build a call without and inline an appendix nobody has ever needed.

   Read chapter
5. 5

   Deferral fails when the agent cannot act without what you moved

   Prerequisites — obtain a scoped token, set the region — pushed into `setup.md` and mentioned in a closing line produce runs that follow every visible instruction and die at the first API call. The same boundary error hides behind 'see examples/ for the required format': the constraint was never in context, so emphasis on the pointer changes nothing. Tell this apart from a routing failure before you reach for capital letters, then pick between the two real remedies — inline the material, which charges every run that loads the body for something a minority of tasks need, or make the fetch a numbered step, which costs a round trip and leaves one more instruction the model can skip.

   Read chapter
6. 6

   A deferred read resolves against the wrong directory in a clean container

   `./reference/error_codes.md` works when you run from the skill's own directory and fails everywhere else, because the path resolves against the agent's working directory. Worse, a teammate in a fresh container often gets no error at all — a plausible answer assembled from general knowledge. Design the check that proves the file was actually read, and understand why a golden-output diff is the wrong instrument.

   Read chapter
7. 7

   An 18% token saving measured only on requests that selected correctly

   Comparing deferred loading against loading every body upfront needs three numbers — prompt tokens, latency, task success — and a fourth thing the experiment cannot see. Success is measured on runs where the right skill was chosen, so requests that thinner metadata caused nothing to match are invisible. Learn which result justifies stopping deferral for one specific body, and how to report the saving honestly.

   Read chapter