Equipping agents for the real world with Agent Skills
by Anthropic
Anthropic's design rationale for Agent Skills — why a folder of Markdown beats a protocol, explained by the people who chose it.
Overview
Published 16 October 2025 by Barry Zhang, Keith Lazuka and Mahesh Murag, this is Anthropic's design rationale for Agent Skills rather than its API reference. It runs through seven sections: an introduction positioning skills as the answer to specialising a general agent, the anatomy of a skill, skills and the context window, skills and code execution, developing and evaluating skills, security considerations, and the future of the format. The core argument is progressive disclosure, described as a multi-level loading model — only a skill's YAML metadata, its name and description, sits in context at startup; the body of SKILL.md loads when Claude judges the skill relevant to a request; and any additional bundled files load only when the instructions point at them. The authors liken this to a well-organised manual that opens with a table of contents, and then draw the consequence that actually matters: because an agent with a filesystem and code execution tools never has to read a skill in its entirety, the amount of material a skill can carry is effectively unbounded. The worked example is the PDF skill — a SKILL.md referencing reference.md and forms.md, plus a Python script that reads a PDF and extracts its form fields, which Claude executes without loading either the script or the PDF into the context window. The security section is short but pointed, treating an installed skill as third-party executable code. Independent readers engaged immediately: Simon Willison called skills 'maybe a bigger deal than MCP' the same day on the token-cost argument, while Tom MacWright's first-run writeup four days later found Claude itself generating a malformed skill folder and flagged dependency portability between local and sandboxed execution as unresolved.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Guide
- Cost
- Free
- Duration
- ~15-20 min read
- Provider
- Anthropic
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓Understand the three-level progressive disclosure model and what loads into context at each stage
- ✓Structure a skill directory so reference material and scripts stay out of context until needed
- ✓See why bundling executable scripts beats having the model regenerate equivalent code each time
- ✓Grasp why a skill's context cost is bounded by its metadata, not by its total bundled size
- ✓Evaluate a skill you have written, and iterate on the description that governs when it triggers
- ✓Assess the security exposure of installing a skill from an untrusted source
- ✓Understand the design argument for skills over a protocol-based approach such as MCP
Highlights
- •It is the primary source: the post that introduced the format, by the engineers who designed it
- •Argues from a concrete worked example — the PDF skill with its reference files and form-filling script — rather than from abstractions
- •The 'effectively unbounded context' claim is the single idea that explains every other design choice in the format
- •Short enough to read before touching the docs, and it makes the reference documentation legible afterwards
- •Triggered substantive independent analysis the same week from Simon Willison and Tom MacWright, both worth reading alongside it
Who It’s For
Best For
- ✓Engineers deciding between Agent Skills and MCP for extending an agent's capabilities
- ✓Developers who read the Skills reference docs and want the reasoning behind the format
- ✓Platform and security teams assessing what installing a third-party skill actually permits
- ✓Anyone designing their own agent harness who wants a proven context-management pattern
Prerequisites
- •Familiarity with LLM agents, context windows and why context budget is a hard constraint
- •Basic understanding of tool use and code execution in an agent loop
- •No coding required to read it, though the PDF example assumes you can follow Python
FAQ
What is Equipping agents for the real world with Agent Skills?
The Anthropic engineering post that introduced Agent Skills on 16 October 2025. It walks through the anatomy of a skill, the three-level progressive disclosure model, how skills combine with code execution, how to develop and evaluate them, and the security consequences of installing one. Read it before the reference docs — it explains why the format looks the way it does, which is what makes the docs make sense.
Is Equipping agents for the real world with Agent Skills free?
Equipping agents for the real world with Agent Skills is free to access.
What level is Equipping agents for the real world with Agent Skills for?
Equipping agents for the real world with Agent Skills is aimed at a intermediate audience. Recommended background: Familiarity with LLM agents, context windows and why context budget is a hard constraint, Basic understanding of tool use and code execution in an agent loop, No coding required to read it, though the PDF example assumes you can follow Python.
How long does Equipping agents for the real world with Agent Skills take?
Expect roughly ~15-20 min read. Most learners work through it at their own pace.
What will I learn from Equipping agents for the real world with Agent Skills?
You'll learn: Understand the three-level progressive disclosure model and what loads into context at each stage; Structure a skill directory so reference material and scripts stay out of context until needed; See why bundling executable scripts beats having the model regenerate equivalent code each time; Grasp why a skill's context cost is bounded by its metadata, not by its total bundled size; Evaluate a skill you have written, and iterate on the description that governs when it triggers; Assess the security exposure of installing a skill from an untrusted source; Understand the design argument for skills over a protocol-based approach such as MCP.
Topics
Sources
This page was written from 3 sources, 2 on domains other than anthropic.com.