An Agent Skill is a folder of files — instructions, reference material, helper scripts — that teaches Claude how to perform a specific kind of task. The anchor file is SKILL.md: a Markdown document with YAML frontmatter declaring a name (max 64 characters; lowercase letters, numbers, and hyphens, with the reserved words "anthropic" and "claude" disallowed) and a description (max 1024 characters). The description matters operationally: it tells Claude when the skill applies, so Claude loads the full instructions only when the task calls for them. Supporting files can include templates, style guides, and code that Claude runs in its sandboxed container.
How Skills are referenced in the API
On the Messages API, Skills are a beta feature enabled with two headers — code-execution-2025-08-25 and skills-2025-10-02 — plus files-api-2025-04-14 if you upload or download container files. Because skills execute inside the code execution sandbox, every request using them must also include the code execution tool in tools. You then select up to 8 skills per request via the container parameter:
from anthropic import AnthropicAWS # Claude Platform on AWS
client = AnthropicAWS()
resp = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv"},
]},
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
messages=[{"role": "user",
"content": "Build the Q3 variance workbook from the data."}],
)Anthropic ships pre-built skills for common document work — pptx, xlsx, docx, and pdf — with date-based versions. Custom skills get generated IDs and are managed through a dedicated Skills API (POST/GET /v1/skills, per-skill version endpoints, and deletion). Uploads must stay under 30 MB, with all files sharing a common root directory and SKILL.md at the top level. Files a skill produces (that finished spreadsheet, say) come back as file IDs you download via the Files API, and long-running skill work can pause with stop_reason: "pause_turn" — you continue by sending the response back within the same container.
Why this beats raw system prompt text for governance
Functionally, a skill and a very good system prompt overlap. Organizationally, they are different animals:
| Concern | Raw system prompt | Skill |
|---|---|---|
| Versioning | Whatever your codebase does | Explicit versions; requests can pin one or track latest |
| Reuse | Copy-paste across apps | One skill ID referenced by many applications |
| Review & audit | Buried in application diffs | A discrete uploadable artifact with its own lifecycle API |
| Payload | Text only | Instructions plus scripts and reference files, loaded on demand |
| Context cost | Always in context | Description always visible; full content loaded when relevant |
For an enterprise, the pin-or-track choice is the quiet win: production systems can pin a reviewed skill version while a platform team iterates on the next one, then roll forward deliberately — the same discipline you already apply to software dependencies, applied to prompts.
Availability and caveats
Agent Skills on the Messages API are in beta on the first-party Claude API, Claude Platform on AWS, and Microsoft Foundry, and not available on Amazon Bedrock or Google Vertex AI — a direct consequence of the code execution dependency, since those platforms lack the sandbox. Skills are also not eligible for Zero Data Retention. Two scope notes: this article covers the Messages API surface, which is distinct from how skills attach to Managed Agents; and treat skill contents like code from a supply-chain standpoint — review what goes into SKILL.md and its scripts before uploading, because Claude will act on it.
Where to go next
Read code execution to understand the container skills run in, and the Files API for retrieving generated documents. The feature matrix tracks beta status by platform.