🪜 Progressive disclosure in practice
You’ve already seen the 3 levels in 3.2. Here we put them into practice: the goal is for the agent to load only what you need, when you need it. An advanced skill is like a menu — SKILL.md shows the options, and each file enters the context only when that route is chosen.
The goal
For an AWS task, the agent reads aws.md and ignores gcp.md and azure.md. The context loads one-third of the content. This is how skills like azure-ai (358k) cover dozens of services without exceeding the context limit.
🗂️ references/ by Domain
The canonical skill-creator pattern: when a skill covers multiple domains, organize by variant and let the SKILL.md handle the selection. The agent reads only the relevant reference file.
domain organization structure (from skill-creator):
cloud-deploy/
├── SKILL.md # workflow + seleção
└── references/
├── aws.md # lido só em tarefas AWS
├── gcp.md # lido só em tarefas GCP
└── azure.md # lido só em tarefas Azure
In the body, routing is explicit — a table that says "if the domain is X, read Y":
routing in the SKILL.md body:
## Selecione o provedor | Provedor | Leia | |----------|---------------------| | AWS | references/aws.md | | GCP | references/gcp.md | | Azure | references/azure.md | Read ONLY the file for the user's provider.
💡 Pro tip
A single 900-line file forces the agent to load everything. Three 300-line files let it pick just one—saving 66% of the context. Maintenance also becomes trivial: you edit azure.md without touching the rest.
⚙️ scripts/ that run without context
The most powerful Level 3 move: a script runs, and the agent only receives the result — the code never enters the context. For deterministic tasks (same input → same output), this is more reliable and cheaper than instructing the agent to "reason" through each step.
✗ Instructions in the body
- ✗"Parse the CSV, add up column 3, format..."
- ✗The agent may get the arithmetic wrong
- ✗Wastes tokens reasoning through the obvious
✓ Level 3 script
- ✓"Run
python scripts/sum.py" - ✓Exact result, every time
- ✓Code doesn’t take up context
in the body: point to it and run it, don’t paste the code:
## Steps 1. Run `python scripts/package_skill.py <path>` to bundle the skill into a .skill file. 2. The script prints the output path — return it. # o conteúdo de package_skill.py NUNCA entra # no contexto; só a saída do comando.
Extraction signal
If you notice the agent rewriting the same helper on every run, that’s the sign: write it once, put it in scripts/, and tell the skill to use it. That’s exactly what skill-creator recommends in the iteration loop.
📑 Table of contents in files >300 lines
The skill-creator rule: any reference file with more than 300 lines gets a table of contents at the top. This lets the agent jump straight to the right section without rereading the entire file.
index at the top of a long reference:
# Guia AWS ## Índice - [IAM & permissões](#iam) - [S3 & storage](#s3) - [Lambda & serverless](#lambda) - [Networking (VPC)](#vpc) ## IAM ...
💡 Pro tip
If a reference is more than ~300 lines with the TOC and still feels too big, that’s a sign to split it into two files by subtopic. The TOC is the first remedy; splitting is the second.
📏 SKILL.md <500 lines + hierarchy with pointers
The golden rule: keep the body under 500 lines. As you approach the limit, don't cut content — add a layer of hierarchy with clear pointers on where the agent should go next.
Identify what's a detail
Edge cases, large tables, and long examples rarely need to be in the main body.
Move to references/
Move it out of the body and into a dedicated reference file for each subtopic.
Leave a pointer in the body
"See references/schemas.md for the full schema" — say when to read it.
real pointers (skill-creator style):
See `references/schemas.md` for the full schema (including the `assertions` field). The references/ directory has more docs: - `references/schemas.md` — JSON structures - `references/eval-format.md` — eval layout
Why the limit matters
The entire body enters the context with every activation. Long bodies dilute the agent’s attention and cost tokens every time. A hierarchy with pointers incurs the cost only when the detail is actually needed.
🎨 assets/ and the final checklist
The folder assets/ stores files used in the output: HTML templates, fonts, icons, boilerplate. Unlike references/ (which the agent reads to learn), assets are filled in or copied into the final output — like the assets/eval_review.html that skill-creator fills with data.
the three directories, with distinct roles:
scripts/ → executado (resultado no contexto) references/ → lido (aprende sob demanda) assets/ → preenchido (vai pro output final)
Sharp multi-file skill checklist
- ✓SKILL.md under 500 lines, with clear pointers
- ✓references/ split by domain; the agent reads only what’s relevant
- ✓TOC in every reference file over 300 lines
- ✓Deterministic tasks became scripts/ that run without context
- ✓assets/ only with files that go into the output
- ✓Each file has a corresponding pointer in the body
💡 Final tip
Well-done multi-file structure is what separates a toy skill from one like azure-ai or supabase. Once you’ve mastered the anatomy, the next frontier is the creation loop—testing, evaluating, and optimizing the description—which is exactly what Track 4 is about.
✅ Module Summary
Next:
Track 4 — ⚙️ How to Create (the loop): capture intent, draft, test with realistic prompts, evaluate, and optimize the description until the skill is sharp.