Using Agent Skills with the API — Claude Docs
by Anthropic (Claude Docs)
Wire pre-built and custom Agent Skills into your own app through the Claude API.
Overview
Anthropic's official guide to using Agent Skills programmatically through the Claude API, as distinct from the Claude Code or claude.ai experience. It opens with prerequisites: an API key, the code execution tool enabled (Skills run inside it), a compatible model, and three beta headers — code-execution-2025-08-25, skills-2025-10-02, and files-api-2025-04-14 when you are moving files. It then contrasts the two skill sources in a table: Anthropic-authored skills use type 'anthropic' with short IDs (pptx, xlsx, docx, pdf) and date-based versions such as 20251013 or 'latest', while custom skills use type 'custom', generated identifiers like skill_01AbCdEf..., epoch-timestamp versions, and stay private to your workspace. Custom skills are uploaded with POST /v1/skills: a SKILL.md at the top level whose frontmatter name is at most 64 characters of lowercase letters, numbers and hyphens and whose description is at most 1024 characters, with all files under a common root directory matching the skill name and under 30 MB uncompressed, shipped as a zip archive or individual files. Skills are attached per request through the container parameter, up to eight at a time. The guide also covers listing, retrieving, deleting and versioning skills, reusing container.id across turns, downloading generated files via the Files API, and looping on the pause_turn stop reason for long-running operations. Samples appear in cURL, Python, TypeScript, C#, Go, Java, PHP and Ruby.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~20 min read
- Provider
- Anthropic (Claude Docs)
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓The three beta headers required before the Skills API will respond
- ✓How Anthropic-authored and custom skills differ in identifier and version format
- ✓Uploading a custom skill via POST /v1/skills with its SKILL.md frontmatter constraints
- ✓Attaching up to eight skills per request through the container parameter
- ✓Reusing container.id to keep execution state across a multi-turn conversation
- ✓Handling the pause_turn stop reason so long-running skill work runs to completion
- ✓Downloading skill-generated files through the Files API using the returned file_id
Highlights
- •Spells out the hard limits — eight skills per request, 30 MB upload, 64-character names
- •Side-by-side table comparing Anthropic-authored and custom skill versioning schemes
- •Runnable request samples in eight languages plus cURL and the ant CLI
- •Covers the whole lifecycle: create, list, retrieve, version and delete
- •Makes clear that Skills ride on the code execution tool, the detail most integrations miss
Who It’s For
Best For
- ✓Backend engineers wiring Skills into their own product
- ✓Teams versioning and shipping custom skills programmatically
- ✓Developers who already use Claude Code Skills and need the API equivalent
Prerequisites
- •A Claude API key and working familiarity with the Messages API
- •Understanding of the code execution tool and container-based execution
- •Basic knowledge of the SKILL.md format and its YAML frontmatter
FAQ
What is Using Agent Skills with the API — Claude Docs?
The official guide to using Agent Skills programmatically rather than through Claude Code or claude.ai. It covers the required beta headers, referencing Anthropic's pre-built skills by short ID, uploading and versioning custom skills through /v1/skills, and attaching them per request via the container parameter. For backend engineers integrating Skills into a product.
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: A Claude API key and working familiarity with the Messages API, Understanding of the code execution tool and container-based execution, Basic knowledge of the SKILL.md format and its YAML frontmatter.
How long does Using Agent Skills with the API — Claude Docs take?
Expect roughly ~20 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 before the Skills API will respond; How Anthropic-authored and custom skills differ in identifier and version format; Uploading a custom skill via POST /v1/skills with its SKILL.md frontmatter constraints; Attaching up to eight skills per request through the container parameter; Reusing container.id to keep execution state across a multi-turn conversation; Handling the pause_turn stop reason so long-running skill work runs to completion; Downloading skill-generated files through the Files API using the returned file_id.
Topics
Sources
This page was written from 3 sources, 2 on domains other than platform.claude.com.