Getting Started with Agent Skills in the API

Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes. This tutorial shows you how to enable Skills, make a simple request, and access the generated file.

Prerequisites

• Anthropic API key
• Python 3.7+ or curl installed
• Basic familiarity with making API requests

What are Agent Skills?

Pre-built Agent Skills extend Claude's capabilities with specialized expertise for tasks like creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:

• PowerPoint (pptx): Create and edit presentations
• Excel (xlsx): Create and analyze spreadsheets
• Word (docx): Create and edit documents
• PDF (pdf): Generate PDF documents

Step 1: List Available Skills

First, let's see what Skills are available. We'll use the Skills API to list all Anthropic-managed Skills:

import anthropic

client = anthropic.Anthropic()

# List Anthropic-managed Skills
skills = client.beta.skills.list(
    source="anthropic",
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title}")

You should see: pptx, xlsx, docx, and pdf.

This API returns each Skill's metadata: its name and description. Claude loads this metadata at startup to know what Skills are available. This is the first level of progressive disclosure, where Claude discovers Skills without loading their full instructions yet.

Step 2: Create a Presentation

Now we'll use the PowerPoint Skill to create a presentation about renewable energy. We specify Skills using the container parameter in the Messages API:

import anthropic

client = anthropic.Anthropic()

# Create a message with the PowerPoint Skill
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create a presentation about renewable energy with 5 slides"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

print(response.content)

Breaking Down the Request

• container.skills: Specifies which Skills Claude can use
• type: "anthropic": Indicates this is an Anthropic-managed Skill
• skill_id: "pptx": The PowerPoint Skill identifier
• version: "latest": The Skill version set to the most recently published
• tools: Enables code execution (required for Skills)
• Beta headers: code-execution-2025-08-25 and skills-2025-10-02

When you make this request, Claude automatically matches your task to the relevant Skill. Since you asked for a presentation, Claude determines the PowerPoint Skill is relevant and loads its full instructions: the second level of progressive disclosure. Then Claude executes the Skill's code to create your presentation.

Step 3: Download the Created File

The presentation was created in the code execution container and saved as a file. The response includes a file reference with a file ID. Extract the file ID and download it using the Files API:

# Extract file ID from response
file_id = None
for block in response.content:
    if block.type == 'tool_use' and block.name == 'code_execution':
        # File ID is in the tool result
        for result_block in block.content:
            if hasattr(result_block, 'file_id'):
                file_id = result_block.file_id
                break

if file_id:
    # Download the file
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Save to disk
    with open("renewable_energy.pptx", "wb") as f:
        file_content.write_to_file(f.name)

    print(f"Presentation saved to renewable_energy.pptx")

Try More Examples

Now that you've created your first document with Skills, try these variations:

Create a Spreadsheet

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create a quarterly sales tracking spreadsheet with sample data"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Create a Word Document

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "docx",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Write a 2-page report on the benefits of renewable energy"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Generate a PDF

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "pdf",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Generate a PDF invoice template"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Understanding Beta Headers

Using Skills via the API requires three beta headers:

1. code-execution-2025-08-25: Skills run in the code execution container
2. skills-2025-10-02: Enables Skills functionality
3. files-api-2025-04-14: Required for uploading/downloading files to/from the container

Best Practices

Use Specific Requests

The more specific your request, the better Claude can leverage the appropriate Skill:

• ✓ "Create a presentation about renewable energy with 5 slides"
• ✗ "Make something about energy"

Include Context When Needed

Provide relevant context for better results:

content: "Create a quarterly sales tracking spreadsheet with sample data including Q1-Q4 2024 revenue, region breakdown, and top 5 products by sales volume"

Handle File Downloads Gracefully

Always extract file IDs safely and handle cases where files might not be created:

try:
    # Extract and download file
    file_id = extract_file_id(response)
    if file_id:
        download_and_save_file(file_id)
    else:
        print("No file was created in the response")
except Exception as e:
    print(f"Error processing file: {e}")

Next Steps

Now that you've used pre-built Agent Skills, you can:

1. Create Custom Skills: Upload your own Skills for specialized tasks
2. Learn the Authoring Guide: Understand best practices for writing effective Skills
3. Explore Skills in Claude Code: Learn about Skills in Claude Code
4. Use the Agent SDK: Use Skills programmatically in TypeScript and Python
5. Check the Cookbook: Explore example Skills and implementation patterns

Common Issues

"Skill not found" Error

• Verify you're using the correct skill_id (pptx, xlsx, docx, pdf)
• Ensure the skills-2025-10-02 beta header is included

"File not created" Issue

• Check that code_execution_20250825 is in both betas array and tools array
• Verify files-api-2025-04-14 header is included when downloading files

Permission Errors

• Ensure your API key has the necessary permissions
• Check that the model supports code execution (claude-sonnet-4-5-20250929 or later)

Congratulations! You've successfully created your first documents using Agent Skills. Continue exploring to unlock more powerful capabilities.