Source: Using Agent Skills with the API (Claude Platform docs)
How to attach Anthropic and custom skills to Messages API calls: container parameter, code execution tool, versions, limits, container reuse and pause_turn.
Contents
- What: official documentation
- Publisher: Anthropic
- Date: living document, read 2026-11-14
- Original: Using Agent Skills with the API
Summary
The programmatic side of skills: uploading, versioning and attaching them to requests, and running multi-turn work in the same sandbox container.
Key claims
- Request shape:
container.skillsis a list of{type: anthropic|custom, skill_id, version}; the code execution tool (code_execution_20250825) must be intools. - Limits (as of 2026-11): up to 20 skills per request; custom skill upload up to 30 MB uncompressed;
display_nameup to 255 chars. - Versions: Anthropic skills use date versions (e.g.
20251013), custom skillsskver_...ids;latestfloats, pinning gives stability. New versions are full snapshots and must keep the samename. - Skill files are copied into the container under
/skills/{skill-name}/; metadata goes into the system prompt. - Multi-turn: reuse
container.idfrom the previous response; onstop_reason: pause_turn, send the content back as an assistant turn in the same container or files are lost. - Generated files come back as
file_ids in code-execution results and are downloaded with the Files API. - Custom skills are scoped to the workspace, not the end user; use one workspace per tenant in multitenant apps.