Chapter 3 of 14 · Understand · 5 min read
What agent skills are and how progressive disclosure works
An agent skill is a folder that teaches an agent how to do one kind of job. At its centre is a file called SKILL.md: a few lines of metadata saying what the skill is and when to use it, followed by instructions in plain Markdown. The clever part isn’t the file format. It’s how agents load skills, a pattern called progressive disclosure, which lets you install a large library of skills without filling the agent’s context window. This chapter explains both.
What a skill looks like
A skill is just a directory. The only required file is SKILL.md. Everything else is optional.
A typical skill folder
release-notes/
├── SKILL.md # required: frontmatter + instructions
├── template.md # optional: a file the agent fills in
├── reference/
│ └── style-guide.md # optional: longer detail, read only when needed
└── scripts/
└── list_commits.sh # optional: a script the agent can runSKILL.md begins with YAML frontmatter: a block of metadata between two lines of three dashes. Two fields matter everywhere: name and description. After the frontmatter comes the body, written the way you would brief a capable colleague.
SKILL.md
---
name: release-notes
description: Write user-facing release notes from recent commits and merged pull requests. Use when the user asks for release notes, a changelog entry or a "what's new" summary.
---
# Release notes
1. Run scripts/list_commits.sh to get commits since the last tag.
2. Group changes into New, Improved and Fixed. Skip internal refactors.
3. Write each item for users, not developers: say what they can now do.
4. Fill in template.md and keep the whole thing under 300 words.
5. For tone and banned words, see reference/style-guide.md.name: a short identifier in lowercase with hyphens, usually matching the folder name.description: what the skill does and when to use it. The agent relies on this line to decide whether the skill is relevant, so it is the most important text in the folder.- The body: steps, rules, examples and pitfalls. It can point to other files in the folder by relative path.
Progressive disclosure, in three levels
Progressive disclosure means showing information only when it’s needed. Skills apply it to the agent’s context. Instead of loading every skill in full, the agent loads them in layers.
| Level | What is loaded | When | Context cost |
|---|---|---|---|
| 1. Metadata | Each skill’s name and description | At the start of every session, for all installed skills | Tiny: a line or two per skill |
| 2. Instructions | The full body of SKILL.md | When the agent decides the skill matches the task | Moderate: the length of the file |
| 3. Resources | Extra files and script output | Only when the instructions point to them and the task needs them | Whatever is actually read; scripts can run without their code being read at all |
Level 1: the menu
When a session starts, the agent is given a compact list of every installed skill, just the names and descriptions. Think of it as a menu. Because each entry is so short, you can have many skills installed and the cost stays small. The agent can’t see the instructions yet; it only knows what is available.
Level 2: opening the playbook
When your request matches a description (“write the release notes for this sprint”), the agent reads that skill’s SKILL.md. Now the instructions are in context and the agent follows them. You usually don’t have to name the skill or run a command. You ask for the task in your own words, and the description does the matching.
Level 3: reaching for the details
Good skills keep SKILL.md focused and push bulky material into separate files: long reference guides, templates, examples, data. The body says when each one is relevant (“for the API error codes, see reference/errors.md”), and the agent opens it only if the task needs it. Scripts are even more efficient. The agent can run a script and read only its output, so a large, reliable program costs almost nothing in context.
Progressive disclosure is why skill authors obsess over descriptions and keep SKILL.md short. Level 1 decides whether the skill is used at all; level 2 should contain only what every use needs; everything else belongs in level 3.
Why this design works
- Scale: you can install dozens of skills and pay only for the few lines of each description until a skill is used.
- Focus: the agent sees detailed instructions only for the task in hand, so they aren’t drowned out by everything else.
- Reliability: deterministic jobs such as parsing a file or validating output can be done by a script instead of being re-improvised each time.
- Portability: a skill is plain files. It can live in a Git repository, be reviewed like code and be shared as a folder or ZIP.
What skills are not
A skill doesn’t give an agent new access. If an agent can’t reach your database, installing a database skill won’t change that; you also need a tool or MCP server that connects to it. A skill also isn’t a hidden program: its instructions are text the model reads and follows, and its scripts run through the agent’s normal tools, subject to the same permissions. That’s good news, because it means you can read a skill and know what it will ask the agent to do.
Because skills are instructions the agent follows, a malicious skill can steer an agent just as well as a helpful one can. Read SKILL.md and any scripts before installing a skill from someone you don’t know. Chapter 6 has a review checklist.
A growing, shared format
The SKILL.md format began with Anthropic’s Claude products and has been adopted by other agents and tools, so a well-written skill is increasingly portable between them. Hosts differ in the details, such as where skills are installed and which optional frontmatter fields they understand, but the core of a folder with a SKILL.md, a name and a description is the same.
Skill CreatorAgent skillAnthropic’s skill for creating and improving skills.Agent skill · MIT
Writing Skills GuideAgent skillA skill about writing skills, from the Superpowers collection.Agent skill · MIT
Agent SkillsOpen sourceA readable collection of engineering skills to learn from.★ 113k · MITKey takeaways
- A skill is a folder with a SKILL.md: frontmatter with
nameanddescription, then Markdown instructions. - Agents load descriptions first, the body when relevant and extra files only when needed.
- The description decides whether a skill is used; keep it specific.
- Skills add know-how, not access. Pair them with tools or MCP servers when they need to reach other systems.
Put it into practice
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Written by the AI Tool Garage editors. Tool details link to their catalogue pages, which are refreshed weekly; spotted something out of date? Tell us.