Using Agent Skills with the API — Claude Docs
by Anthropic (Claude Docs)
Wire pre-built and custom Skills into your own app via the Claude API.
Overview
This official guide shows how to use both pre-built and custom Agent Skills with the Claude API. It documents the three required beta headers (code-execution-2025-08-25, skills-2025-10-02, and files-api-2025-04-14), and how to reference pre-built Anthropic skills by short IDs (pptx, xlsx, docx, pdf) with date-based or 'latest' versions. For custom Skills, it covers uploading via POST /v1/skills (a SKILL.md at the top level with name/description frontmatter, uploaded as files or a zip up to 30 MB, returning a skill_id), and specifying skills in the Messages API through the container parameter — up to 8 Skills per request, mixing 'anthropic' and 'custom' types, reusable across multi-turn conversations via container.id. It also explains downloading generated files through the Files API, handling the pause_turn stop reason for long-running operations, and that Skills are not eligible for Zero Data Retention.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~15 min read
- Provider
- Anthropic (Claude Docs)
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓The three beta headers required to call Skills via the API
- ✓Referencing pre-built skills by skill_id and version
- ✓Uploading and versioning custom skills through /v1/skills
- ✓Structuring the container.skills parameter in Messages API requests
- ✓Retrieving generated files and handling pause_turn for long tasks
Highlights
- •Concrete request/response JSON for the container parameter
- •Covers both pre-built and custom skill flows
- •Notes the 8-skills-per-request and 30 MB upload limits
Who It’s For
Best For
- ✓Backend engineers integrating Skills into an app
- ✓Developers managing custom skill versions programmatically
Prerequisites
- •Claude API key and Messages API familiarity
- •Understanding of the code execution tool
FAQ
What is Using Agent Skills with the API — Claude Docs?
The official guide to using Agent Skills programmatically: the required beta headers, referencing pre-built skills by skill_id, uploading custom skills via /v1/skills, and the container parameter. Best for developers integrating Skills into their own agents.
Is Using Agent Skills with the API — Claude Docs free?
Using Agent Skills with the API — Claude Docs is free to access.
What level is Using Agent Skills with the API — Claude Docs for?
Using Agent Skills with the API — Claude Docs is aimed at a intermediate audience. Recommended background: Claude API key and Messages API familiarity, Understanding of the code execution tool.
How long does Using Agent Skills with the API — Claude Docs take?
Expect roughly ~15 min read. Most learners work through it at their own pace.
What will I learn from Using Agent Skills with the API — Claude Docs?
You'll learn: The three beta headers required to call Skills via the API; Referencing pre-built skills by skill_id and version; Uploading and versioning custom skills through /v1/skills; Structuring the container.skills parameter in Messages API requests; Retrieving generated files and handling pause_turn for long tasks.