Skills
How it works
A skill is a directory with a SKILL.md file that must begin with YAML frontmatter containing the required name and description fields. Progressive disclosure operates on three levels: (1) at startup the metadata (name + description) of every skill is loaded into the system prompt so the agent knows when to use it; (2) when the agent deems a skill relevant, it reads the full SKILL.md body into context; (3) as needed, the agent navigates to additional files bundled in the directory (e.g. reference.md, forms.md) and reads them only when required. A skill can also bundle scripts that the agent runs as tools via code execution, without loading the script or data into context. It requires an agent environment with a filesystem and a code execution tool.
Problem solved
General-purpose agents lack built-in, domain-specific procedural knowledge, and hard-coding it into a prompt or system prompt is costly, does not scale, and is neither reusable nor portable across tasks and platforms. Agent Skills encapsulate that knowledge into a single, on-demand resource.
Components
The required file in a skill directory; consists of YAML frontmatter plus a Markdown body.
Required metadata loaded into the system prompt at startup; drives skill discovery and triggering.
The main instruction body, loaded into context only once the skill is judged relevant.
Optional reference files, templates and data bundled in the directory, read by the agent only on demand.
Official
Optional code (e.g. Python) run by the agent as a tool, giving deterministic results without loading the script into context.
Official
Implementation
If the description field is too vague or does not state when to use the skill, the agent will not trigger it.
An overly broad description makes the agent load the skill even in irrelevant situations, wasting context.
Skills with scripts and progressive disclosure assume an environment with a filesystem and a code execution tool; without them they will not work fully.
Evolution
On October 16, 2025 Anthropic introduces Agent Skills in Claude, Claude Code, the API and the Agent SDK, along with pre-built document skills (PDF, Word, Excel, PowerPoint).
On December 18, 2025 Anthropic publishes Agent Skills as an open standard for cross-platform portability.
Hyperparameters (configurable axes)
The frontmatter description determines when the agent triggers the skill; a weak description leads to under- or over-triggering.
The skill identifier; part of level-1 metadata and the basis for invocation (e.g. /name).
The number and structure of bundled files determine how much context the agent reads only on demand.
Optional scoping of the tools/permissions a skill may use.
Execution paradigm
This is a context-engineering paradigm, not a model-compute mode: skills are disclosed conditionally, depending on the task.
The agent matches each skill's metadata (name + description) in the system prompt against the current task and conditionally loads only the relevant skills.
Hardware requirements
Agent Skills is a context-engineering / orchestration pattern independent of the accelerator; it only requires an agent environment with a filesystem and code execution.