We started this chapter noting that too many tools make an agent worse: a long prompt, and a model overwhelmed by options. A workspace helped, but a capable agent still needs to know about many things.
Agent skills solve the crowding the way a person does. A new employee does not memorise every company manual on day one. They learn that the manuals exist, and read the right one when a task calls for it.
A skill is a folder
A skill packages a capability: what it is, how to use it, and the code that does it. In this pattern each skill is a folder with a document describing it and whatever code it needs.
skills/
pdf-merge/
SKILL.md # what it does, and how to use it
merge.py # the code that does it
excel-report/
SKILL.md
report.py
The SKILL.md is the manual: a one-line description at the top, then detailed instructions below. The
agent reads the description to know the skill exists, and reads the full document only when it decides
to use the skill.
Progressive disclosure: three levels
The core idea is loading information in stages, so the prompt stays small and the agent still reaches what it needs.
Level 1: the skill list, in the prompt. Only names and one-line descriptions, a few hundred tokens for many skills. The agent always sees this, so it always knows what capabilities exist. For most requests, this is all it needs to pick the right one.
Level 2: the skill's document, on demand. When the agent decides a skill fits, it reads that
skill's SKILL.md in full, using the workspace to open the file. The detailed instructions enter the
context only now, only for the one skill in play.
Level 3: the code runs. Following the document, the agent executes the skill's code in the sandbox. The heavy work happens there, and only the result returns.
| Level | What loads | When | Token cost |
|---|---|---|---|
| 1 | Skill names and one-liners | Always, in the prompt | Hundreds, for all skills |
| 2 | One skill's full document | When the agent picks it | The one skill's doc |
| 3 | The skill's code runs | When the agent uses it | Only the result returns |
Level 1 lists skills in the prompt; level 2 reads one doc on demand; level 3 runs its code in the sandbox.
Why this scales where a tool list does not
Compare the token cost. A hundred tools means a hundred full definitions in the prompt on every call. A hundred skills means a hundred one-line descriptions in the prompt, and the full details of only the skill actually being used.
The two prompts grow differently: one grows with your total capabilities, the other with the capabilities in play right now. The first hits a ceiling; the second stays lean no matter how many skills you add. Progressive disclosure is how an agent can have hundreds of capabilities without a prompt that reads like an encyclopedia.
A worked example: merging PDFs
Watch the three levels on one request: "merge these two PDFs into one."
# Level 1 (already in the prompt): the agent knows a "pdf-merge" skill exists
Action: bash("cat skills/pdf-merge/SKILL.md") # Level 2: read the manual
Observe: "Merge PDFs. Usage: python merge.py out.pdf in1.pdf in2.pdf ..."
Action: bash("python skills/pdf-merge/merge.py merged.pdf a.pdf b.pdf") # Level 3: run it
Observe: Merged 2 files into merged.pdf
The agent knew the skill existed from the one-line description in its prompt, read the details only when the task needed them, and then ran the code. At no point did the full instructions for every other skill clutter its context.
The hierarchy this builds
Step back and the whole chapter's tools fall into a clean structure.
Core tools, always in the prompt: a small set, including execute_python and bash. These are the
primitives.
Skills, discovered at level 1 and read at level 2: capabilities packaged as folders, loaded on demand.
Code, run at level 3: the actual work, executed in the sandbox.
Core tools (always present) execute_python, bash, ...
-> Skills (loaded on demand) pdf-merge, excel-report, ...
-> Code (run in sandbox) the skill's script does the work
Core tools are always present; skills load on demand; the skill's code runs in the sandbox.
What to take from this
- A skill packages a capability as a folder: a document describing it and the code that does it. The agent reads the description always, the full document only when it uses the skill.
- Progressive disclosure loads in three levels: names in the prompt, one document on demand, code in the sandbox. The prompt grows with capabilities in play, not total capabilities.
- The result is a hierarchy: a few always-present core tools, many on-demand skills, and code that runs the work in the sandbox. It scales to hundreds of capabilities without a bloated prompt.
The agent's capabilities are now complete: it reasons, uses tools, retrieves, remembers, plans, and now runs code, works a filesystem, and loads skills on demand. Each new capability is also a new surface, and code execution is the sharpest of them, which is where the security series turns next.