Using Skills with the API

Agent Skills extend Claude's capabilities through organized folders of instructions, scripts, and resources. This guide shows you how to use both pre-built and custom Skills with the Claude API.

For complete API reference including request/response schemas and all parameters, see:

Skill Management API Reference - CRUD operations for Skills
Skill Versions API Reference - Version management

Quick Links

Get started with Agent Skills - Create your first Skill
Best practices - Best practices for authoring Skills

Overview

For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: Equipping agents for the real world with Agent Skills.

Skills integrate with the Messages API through the code execution tool. Whether using pre-built Skills managed by Anthropic or custom Skills you've uploaded, the integration shape is identical—both require code execution and use the same container structure.

Using Skills

Skills integrate identically in the Messages API regardless of source. You specify Skills in the container parameter with a skill_id, type, and optional version, and they execute in the code execution environment.

You can use Skills from two sources:

anthropic: Pre-built Skills like pptx, xlsx, docx, pdf
custom: Your uploaded Skills with IDs like skill_01AbCdEfGhIjKlMnOpQrStUv

Prerequisites

To use Skills, you need:

Anthropic API key from the Console
Beta headers:
- code-execution-2025-08-25 - Enables code execution (required for Skills)
- skills-2025-10-02 - Enables Skills API
- files-api-2025-04-14 - For uploading/downloading files to/from container
Code execution tool enabled in your requests

Using Skills in Messages

Container Parameter

Skills are specified using the container parameter in the Messages API. You can include up to 8 Skills per request.

The structure is identical for both Anthropic and custom Skills—specify the required type and skill_id, and optionally include version to pin to a specific version.

Downloading Generated Files

When Skills create documents (Excel, PowerPoint, PDF, Word), they return file_id attributes in the response. You must use the Files API to download these files.

How it works:

Skills create files during code execution
Response includes file_id for each created file
Use Files API to download the actual file content
Save locally or process as needed

Multi-Turn Conversations

Reuse the same container across multiple messages by specifying the container ID.

Long-Running Operations

Skills may perform operations that require multiple turns. Handle pause_turn stop reasons.

The response may include a pause_turn stop reason, which indicates that the API paused a long-running Skill operation. You can provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you wish to interrupt the conversation and provide additional guidance.

Using Multiple Skills

Combine multiple Skills in a single request to handle complex workflows.

Managing Custom Skills

Creating a Skill

Upload your custom Skill to make it available in your workspace. You can upload using either a directory path or individual file objects.

Requirements:

Must include a SKILL.md file at the top level
All files must specify a common root directory in their paths
Total upload size must be under 8MB
YAML frontmatter requirements:
- name: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words ("anthropic", "claude")
- description: Maximum 1024 characters, non-empty, no XML tags

Listing Skills

Retrieve all Skills available to your workspace, including both Anthropic pre-built Skills and your custom Skills. Use the source parameter to filter by skill type.

Retrieving a Skill

Get details about a specific Skill.

Deleting a Skill

To delete a Skill, you must first delete all its versions. Attempting to delete a Skill with existing versions will return a 400 error.

Versioning

Skills support versioning to manage updates safely:

Anthropic-Managed Skills:

Versions use date format: 20251013
New versions released as updates are made
Specify exact versions for stability

Custom Skills:

Auto-generated epoch timestamps: 1759178010641129
Use "latest" to always get the most recent version
Create new versions when updating Skill files

How Skills Are Loaded

When you specify Skills in a container:

Metadata Discovery: Claude sees metadata for each Skill (name, description) in the system prompt
File Loading: Skill files are copied into the container at /skills/{directory}/
Automatic Use: Claude automatically loads and uses Skills when relevant to your request
Composition: Multiple Skills compose together for complex workflows

The progressive disclosure architecture ensures efficient context usage—Claude only loads full Skill instructions when needed.

Use Cases

Organizational Skills

Brand & Communications

Apply company-specific formatting (colors, fonts, layouts) to documents
Generate communications following organizational templates
Ensure consistent brand guidelines across all outputs

Project Management

Structure notes with company-specific formats (OKRs, decision logs)
Generate tasks following team conventions
Create standardized meeting recaps and status updates

Business Operations

Create company-standard reports, proposals, and analyses
Execute company-specific analytical procedures
Generate financial models following organizational templates

Personal Skills

Content Creation

Custom document templates
Specialized formatting and styling
Domain-specific content generation

Data Analysis

Custom data processing pipelines
Specialized visualization templates
Industry-specific analytical methods

Development & Automation

Code generation templates
Testing frameworks
Deployment workflows

Limits and Constraints

Request Limits

Maximum Skills per request: 8
Maximum Skill upload size: 8MB (all files combined)
YAML frontmatter requirements as specified above

Environment Constraints

Skills run in the code execution container with these limitations:

No network access - Cannot make external API calls
No runtime package installation - Only pre-installed packages available
Isolated environment - Each request gets a fresh container

See the code execution tool documentation for available packages.

Best Practices

When to Use Multiple Skills

Combine Skills when tasks involve multiple document types or domains:

Good use cases:

Data analysis (Excel) + presentation creation (PowerPoint)
Report generation (Word) + export to PDF
Custom domain logic + document generation

Avoid:

Including unused Skills (impacts performance)

Version Management Strategy

For production:

# Pin to specific versions for stability
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Specific version
    }]
}

For development:

# Use latest for active development
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Always get newest
    }]
}

Get started with Agent Skills - Create your first Skill
Best practices - Learn best practices for writing effective Skills
Skills overview - Understand the Skills architecture