Agent Skills are packaged expertise: a folder containing a SKILL.md instruction file plus optional scripts, templates, and reference documents that teach Claude how to do a specific job — fill in your company's contract template, generate a spreadsheet in the house style, follow your incident-report format. The obvious worry is cost. Context window space is the scarcest resource in agent engineering, and if every skill's full instructions sat in the prompt on every request, a well-equipped agent would be an expensive one. Skills avoid this with an architecture Anthropic calls progressive disclosure: content loads in three levels, each only when needed.
The three levels
| Level | What loads | When | Context cost |
|---|---|---|---|
| 1 — Metadata | name + description from the YAML frontmatter | Always, in the system prompt | ~100 tokens per skill |
| 2 — Instructions | The SKILL.md body | When the skill is triggered, read via bash | Under 5k tokens |
| 3+ — Resources & scripts | Bundled files and code | As needed during the task | "Effectively unlimited" |
Level 1 is the only part that is always present. At startup, each skill contributes just its name and description — around 100 tokens — to the system prompt. This is enough for Claude to know the skill exists and what it's for, the way a person knows there's a manual on the shelf without having memorized it.
Level 2 loads when a request actually matches a skill. Claude reads the SKILL.md body from the filesystem using bash, pulling the full instructions (kept under 5k tokens by convention) into context only for the task at hand.
Level 3 and beyond is where skills stop behaving like prompts at all. A skill can bundle reference files — say, a FORMS.md describing every field in a regulatory form — that Claude reads only if the task requires them, and scripts that Claude executes rather than reads.
The trick that makes level 3 cheap: run code, don't read it
Skills run inside the code execution container, and that placement enables the most underappreciated part of the design: when Claude runs a bundled script via bash, only the script's output enters the context window. The script's source code never consumes tokens. A thousand-line validation script that prints "3 errors found, lines 14, 92, 240" costs you one short line of context, not a thousand lines of Python.
This is why Anthropic describes level 3 as effectively unlimited, and it suggests a design principle for custom skills: push deterministic work into scripts. Instructions ("format dates as ISO 8601") burn context every time they're loaded and rely on the model following them; a script that does the formatting costs almost nothing and cannot misremember. The skills docs frame this as three content types — instructions (markdown guidance), code (deterministic scripts), and resources (schemas, templates, examples) — and the leanest skills lean hard on the second and third.
What this means on 3P platforms
The economics above apply wherever Agent Skills run — but they don't run everywhere. On the Messages API surface, skills are available on the first-party Claude API, Claude Platform on AWS, and Microsoft Foundry (where they require a Hosted on Anthropic deployment); they are not available on Amazon Bedrock or Google Vertex AI, which also lack the code execution container skills depend on. If your agents live on Bedrock or Vertex, the documented route to skill-like behavior is the Claude Agent SDK, which loads skills from .claude/skills/*/SKILL.md on your own filesystem and runs on all four 3P surfaces. The full picture is in Agent Skills on 3P Platforms.
Because the description is all Claude sees before choosing a skill, write it the way you'd write a good tool description: specific about what the skill does and when to use it. A skill with a vague description either never triggers or triggers constantly — both waste the architecture.
Where to go next
See the request shape and beta headers in Agent Skills on the Messages API, how runtime constraints differ by surface in Agent Skills Runtime Constraints, and why bundled scripts deserve scrutiny in Auditing Agent Skills Like Installing Software.