agent-skills-progressive-disclosure
verified8efbb372-5987-48f7-8c81-acfc86476a9e
Design and package Agent Skills — Anthropic's file-and-folder pattern (SKILL.md + progressive disclosure) for giving agents procedural knowledge, now a cross-platform open standard.
Metadata
Skill file
# Agent Skills: Progressive Disclosure for Procedural Knowledge
Use when you need to give an agent *procedural* knowledge and reusable expertise —
how to do a multi-step task, an org-specific workflow, or a domain playbook — that
is too large to stuff into a system prompt and too specific for a single function
call. Agent Skills (introduced by Anthropic on 2025-10-16, published as an open
standard on 2025-12-18) package this expertise as files and folders the model loads
only when needed.
## Why this beats system prompts and tools
A monolithic system prompt has three failure modes that Skills fix:
- **Context bloat** — a long fixed prompt burns tokens every call, even when 90% of
it is irrelevant to the current task.
- **Opacity** — tool schemas describe *what* a function does, not *how* to combine
ten steps into a correct workflow.
- **Rigidity** — changing a system prompt is a code deploy; changing a Skill is a
file edit.
Skills are the middle ground: structured instructions + optional scripts/references
that a model discovers and loads on demand. Within weeks of the open standard
release, OpenAI (Codex CLI, ChatGPT), Google (Gemini CLI), GitHub Copilot, and Cursor
all added support, and marketplaces like SkillsMP indexed hundreds of thousands of
skills.
## The three-tier progressive-disclosure structure
The core design principle is **progressive disclosure** — three layers loaded in
order of increasing specificity, so only the information actually needed enters
context:
1. **Layer 1 — Metadata (always in context).** The `name` and `description` fields
in `SKILL.md`'s YAML frontmatter. These are cheap and always visible so the model
can decide *whether* a skill applies. Treat the description like a search query
you expect a future task to match — write what the skill *uniquely* does, not
generic prose.
2. **Layer 2 — The `SKILL.md` body (loaded when relevant).** The full instructions:
steps, gotchas, decision rules. Loaded only after the model decides the skill is
relevant.
3. **Layer 3 — Bundled files (loaded only when needed).** Extra `reference.md`
files, `scripts/` (e.g. a Python helper the agent runs), and `forms.md`/schemas.
These stay on disk until the body explicitly says "read X".
A real skill directory:
```
my-domain-skill/
SKILL.md # name/description + step-by-step instructions
reference.md # deep reference the body points at for edge cases
forms.md # templates/checklists the agent fills out
scripts/parse.py # executable helper, invoked by the body
```
## Writing a good SKILL.md
- **Frontmatter** must carry `name` (kebab-case) and a `description` that is a
precise, trigger-matching summary. The description is the *selection* signal — the
single most important line you write.
- **Body** should open with *when to use / when not to use*, then give ordered,
concrete steps. Prefer imperative, unambiguous instructions over prose.
- **Progressive disclosure discipline**: keep the body short; move tables, long
examples, and reference material into `reference.md` and tell the body to load it
only for specific conditions. A 500-line `SKILL.md` is a system prompt in disguise.
- **Idempotent and verifiable**: give the agent a way to check its own work (run a
script, assert a condition) rather than leaving correctness implicit.
- **Version and test** like code: put skills in a repo, review diffs, and add a small
selection eval (see below).
## Verifying selection accuracy
The failure mode that matters is *wrong selection* — the model ignoring a relevant
skill or invoking an irrelevant one. Build a tiny eval: a set of ~20-50 real task
descriptions annotated with which skill (if any) should fire. Run the model's
selection step over them and measure precision/recall. Iterate on the `description`
wording — a sharper description fixes most selection bugs faster than any other change.
## Pitfalls
- Treating `SKILL.md` as a dumping ground — it becomes a bloated, unreadable prompt.
- Vague descriptions ("helps with data") that never match a real query — the skill
silently never fires.
- Mixing two unrelated capabilities in one skill, forcing the model to load
irrelevant context.
- Hard-coding secrets or environment specifics in the body instead of referencing
them generically.
- No selection eval — you can't tell whether your skill is being used or ignored.
## Verify
- Put the skill in a test agent/CLI and run 3-5 tasks that should trigger it; confirm
the correct file loads (visible in the agent's context or logs).
- Run the selection eval and check the right skill fires for each annotated task.
- Confirm Layer 3 files are *not* loaded for tasks that don't need them (i.e. you
aren't leaking context).Attached files
No attached files.