Skills, and progressive disclosure
A skill is a folder with a SKILL.md in it. The interesting part is not the format. It is what the format lets the runtime avoid loading.
Three levels
That structure answers a whole family of questions phrased as how does an agent have access to more capability than fits in its context. It does not hold the capability. It holds an index of capability and fetches on demand.
Which is the same trick as offloading from the previous lesson, pointed at instructions instead of tool results. A path plus a preview, fetched when wanted. Once you see that both mechanisms are the same idea, module 3 stops being two topics.
The frontmatter
---
name: pdf-extraction # MUST match the directory name, 1 to 64 chars
description: "..." # max 1,024 chars, loaded at startup
license: MIT # optional
compatibility: "..." # optional
metadata: { ... } # optional
allowed-tools: [read_file] # optional
---Two carry hard constraints and both are exam-shaped:
namemust match the directory name, and runs 1 to 64 characters. A mismatch is a broken skill, not a warning, which is why it is the most common cause of a skill that silently does not appear.descriptionis capped at 1,024 characters.
64 and 1,024, name and description, sitting side by side. Do not let them swap. That adjacency is the entire question an examiner would write here.
Why the description cap is not a style guideline
description is level-one metadata. It loads at startup, for every skill, on every run, invoked or not. It is the permanent tax, and the cap is a context budget rather than an editorial preference.
Which tells you what a description is for: it is a routing decision, not documentation. It has exactly one job, which is to let the agent decide whether to open the door. The instructions live behind the door.
The failure mode is a description that tries to be the manual. It burns startup context on every run and it still is not enough to actually perform the task, so it loses on both counts at once.
The optional fields
license, compatibility, metadata and allowed-tools are all optional.
The confusion is worth naming because it comes from somewhere real: in other Agent Skills hosts, allowed-tools is enforced by the harness. Carrying that expectation into deepagents gives you a scoped-looking skill that is not scoped, which is the same shape as the fail-open permission list two modules back.
For the exam, the safe posture is to know all four exist, know that name and description are the constrained ones, and not over-invest in the rest. The distinctions and the two numbers get tested. The optional field list is exactly the sort of thing a reference page hands you in five seconds.
SkillsMiddleware handles all of this, and it sits first in the fixed deep agent stack. As ever, it imports into a plain create_agent if you would rather assemble the thing yourself.
Try it yourself
The three levels
Progressive disclosure is the entire reason skills exist as a separate mechanism. The levels are the mechanism.
Describe the three levels of progressive disclosure for a skill, and say what is in context at each level.
Reveal answer
Level one is metadata: the name and description only, loaded at startup so the agent knows the skill exists and roughly what it is for. Level two is the full body of SKILL.md, loaded when the skill is actually invoked. Level three is resources, the scripts/, references/ and assets/ directories, reached only when the body sends the agent to them. So a skill costs two lines of context until the moment it is needed, which is why you can attach thirty of them without wrecking the window.
Spot the broken skill
This file is at skills/pdf-extraction/SKILL.md and the skill never loads. One line is the reason.
---
name: pdf_extraction
description: "Extract structured tables from PDF invoices."
license: MIT
allowed-tools: [read_file, execute]
---Show answer
Correct answer: C — name uses an underscore and no longer matches the directory name
name must match the directory name, and pdf_extraction does not match pdf-extraction. A mismatch is a broken skill, not a warning, which makes it the single most common cause of a skill that silently does not appear. The allowed-tools option is the tempting one because constraining execute feels like it ought to be special-cased, but allowed-tools is an ordinary optional field and execute is an ordinary tool name.
The two bounded fields
Two fields carry hard limits and they sit next to each other in the frontmatter, which is exactly why an examiner can build a clean question out of them.
Show answer
Correct answer: D — name runs 1 to 64 characters and description is capped at 1,024
name runs 1 to 64 characters and description is capped at 1,024. The first option is the exact swap, and it is the most likely wrong answer because both numbers are real and both fields are adjacent, so the pairing is the only thing being tested. The unbounded option is worth ruling out for a structural reason: description is level-one metadata paid for on every run, so leaving it uncapped would defeat the purpose of the mechanism.
Why the cap is not a style rule
The description limit exists for a reason that tells you what a description is actually for.
Show answer
Correct answer: B — Because every skill's description loads at startup on every run, a permanent tax
description is level-one metadata: it loads at startup, for every registered skill, whether that skill is ever invoked or not. The cap is a context budget. That tells you what a description is for, which is a routing decision rather than documentation. The failure mode is writing a description that tries to be the manual: it burns startup context on every run and still is not enough to perform the task.
Where skills sit in the stack
The fixed deep agent middleware stack has a defined order. Which position does SkillsMiddleware occupy?
Show answer
Correct answer: D — First in the stack, before Filesystem
SkillsMiddleware is first: Skills, Filesystem, SubAgent, Summarization, PatchToolCalls, your middleware, tail. The third option is the one worth killing explicitly, because skills genuinely are supplied by you through the skills parameter, which makes them feel like user middleware. Where you supply configuration and where its handler sits in a fixed stack are different questions.
Write one from memory
In a scratch file, write a complete SKILL.md frontmatter block for a fictional skill, then check it against the lesson.
You included name and description, your name matches your imagined directory exactly including hyphens, and you can name at least three of the four optional fields without looking.