Agent Skills - packaged instructions with progressive disclosure

An Agent Skill is a directory containing a SKILL.md file plus whatever scripts, references and assets it bundles - a way of packaging a procedure so an agent can load it when needed instead of carrying it in the prompt at all times. The problem it solves is concrete: the more capabilities you give an agent, the longer its instructions get, and everything in the system prompt is paid on every request whether it is used or not.

The format - published openly at agentskills.io and used by Anthropic’s own agent tooling - is deliberately simple, which is the point. A skill is not a compiled plugin; it is a folder a person can read and an agent can walk.

The file itself

At minimum, a skill is one file:

my-skill/
└── SKILL.md          # metadata + instructions

SKILL.md opens with YAML frontmatter carrying two required fields:

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, merges PDFs. Use when working with PDF documents.
---

name is a slug - lowercase, hyphens, 64 characters or fewer, matching its directory. Everything else in the frontmatter is optional (license, compatibility, metadata, and an experimental allowed-tools list). The rules are deliberately strict on name and loose everywhere else, because the file’s real job is carried by description.

Progressive disclosure - the design that matters

The point of the format is not that it packages instructions - a prompt does that. It is that it packages them in three tiers that load at three different times:

• Metadata - the name and description of every installed skill are loaded into the system prompt at startup, at roughly a hundred tokens each. The agent knows the skill exists without paying for its contents.
• Instructions - when a task matches a skill’s description, the agent reads the SKILL.md body itself - the workflow, the edge cases, the examples. Recommended under five thousand tokens.
• Resources - scripts, reference documents, templates bundled in the directory are pulled in only when the instructions reach them. A script is executed, not read, so its source never enters context at all.

This is why a hundred skills can coexist without a hundred skills’ worth of prompt: until one triggers, it costs only its frontmatter.

The description is the trigger

Because the agent only ever sees description before deciding whether to open the skill, the description carries the whole selection problem. A vague one - “helps with PDFs” - never triggers. A broad one triggers on everything and misfires. The spec is blunt about it: the description must say what the skill does and when to use it, because it is the only surface the agent matches against.

That makes writing a skill closer to writing a good man page than writing a prompt - you are authoring for a reader that has to decide, from one line, whether to commit context to you.

Where it sits in the stack

A skill is not a tool and not a protocol:

• versus MCP - MCP connects an agent to external capabilities; a skill teaches the agent a procedure it then carries out using whatever tools it already has. They compose: a skill can direct the agent to call MCP tools as part of its procedure.
• versus a prompt - a prompt is read, once, every time; a skill is loaded on demand and can reach for files and scripts that never enter context. A long prompt is a skill with all three levels flattened into one expensive level.
• versus a harness - the harness owns the loop that loads and triggers the skill; the skill is what the loop reads. A skill does not run itself.

Where it breaks

• The description does the whole job of selection. If two skills have overlapping descriptions the model picks the wrong one; if none matches, the capability is invisible. There is no fallback mechanism.
• Level 3 is a security boundary wearing a convenience hat. allowed-tools is still experimental and only pre-approves tools - it does not confine them. A bundled script runs with the agent’s permissions, so a malicious or sloppily-written skill is an execution path, not just a text file.
• It is only as portable as the skills are. The format is open, but a skill that leans on a vendor-specific capability in its compatibility field does not travel between agents that lack it.
• Progressive disclosure does not test itself. A skill can be well-structured and wrong - the format says nothing about whether the procedure produces good output, which is what the eval suite is for.

What this is not for

• One-off instructions that belong in a prompt - the overhead of the format only pays off when the procedure is reused across tasks or teams.
• Exposing external tools or data - that is MCP’s boundary, and a skill that merely wraps a tool adds a layer that earns nothing.
• Anything that must run deterministically - a skill is read by a model that may apply it imperfectly; it is a procedure, not a program.