Using skills via the Claude API

Upload custom skills and use Anthropic’s pre-built skills through the Claude API for programmatic access

The Claude API supports both Anthropic’s pre-built skills and custom skills uploaded via the API. This enables you to build applications that leverage specialized capabilities programmatically.

Quick start

The Skills API allows you to create, manage, and use skills in your API applications:

1. Create a skill

   Upload a skill to your account:

   import anthropic
   
   client = anthropic.Anthropic(api_key="your-api-key")
   
   # Create a skill from a local directory
   skill = client.skills.create(
       name="pdf-processor",
       description="Extract and analyze data from PDF documents",
       content=open("path/to/SKILL.md", "r").read()
   )
   
   print(f"Created skill: {skill.id}")
   
2. Use the skill in a message

   Reference the skill in your API calls:

   message = client.messages.create(
       model="claude-4.5-sonnet",
       max_tokens=1024,
       skills=[skill.id],
       messages=[
           {
               "role": "user",
               "content": "Extract all tables from quarterly-report.pdf"
           }
       ]
   )
   
   print(message.content)
   

For complete API documentation and examples, see the Skills API Quickstart in the Claude API documentation.

Using Anthropic’s pre-built skills

Anthropics provides production-grade skills that you can use directly in your API applications without uploading them yourself.

Available pre-built skills

Document processing

• xlsx: Excel spreadsheet creation and analysis
• docx: Word document generation and editing
• pptx: PowerPoint presentation building
• pdf: PDF reading, extraction, manipulation, and form filling

These are the same skills that power Claude.ai’s document features.

Development tools

• mcp-builder: Generate Model Context Protocol servers
• skill-creator: Create and evaluate new skills programmatically
• webapp-testing: Test web applications systematically
• web-artifacts-builder: Build interactive web components

Creative & design

• algorithmic-art: Generate procedural graphics
• canvas-design: Create visual layouts
• frontend-design: Build UI components
• theme-factory: Develop visual themes

Referencing pre-built skills

To use Anthropic’s pre-built skills, reference them by name:

message = client.messages.create(
    model="claude-4.5-sonnet",
    max_tokens=2048,
    skills=["pdf", "xlsx"],  # Use pre-built skills by name
    messages=[
        {
            "role": "user",
            "content": "Extract data from report.pdf and create an Excel summary"
        }
    ]
)

Creating custom skills

Custom skills extend Claude with domain-specific knowledge and workflows tailored to your application.

Skill structure

A skill consists of a SKILL.md file with YAML frontmatter and markdown instructions:

---
name: customer-support-analyzer
description: Analyze customer support tickets and categorize issues by type, 
  severity, and department. Use when processing support ticket data or 
  analyzing customer feedback patterns.
---

# Customer Support Analyzer

Analyze support tickets and provide structured insights.

## Process

1. Extract ticket information (ID, timestamp, customer, issue description)
2. Categorize issue type: Technical, Billing, Feature Request, Other
3. Assess severity: Critical, High, Medium, Low
4. Route to department: Engineering, Finance, Product, Support
5. Suggest resolution steps based on similar tickets

## Output Format

Provide results as JSON with these fields:
- ticket_id: Ticket identifier (format T-XXXXX)
- category: Issue type (Technical, Billing, Feature Request, Other)
- severity: Priority level (Critical, High, Medium, Low)
- department: Routing destination (Engineering, Finance, Product, Support)
- summary: Brief issue description
- recommended_actions: Array of suggested resolution steps

## Guidelines

- Always validate ticket IDs match format T-XXXXX
- Escalate Critical severity tickets immediately
- Check knowledge base before suggesting new solutions

Uploading skills via API

Python

import anthropic
import os

client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Read skill file
with open("skills/customer-support/SKILL.md", "r") as f:
    skill_content = f.read()

# Create skill
skill = client.skills.create(
    name="customer-support-analyzer",
    description="Analyze and categorize customer support tickets",
    content=skill_content
)

print(f"Skill created: {skill.id}")

# Use the skill
message = client.messages.create(
    model="claude-4.5-sonnet",
    max_tokens=1024,
    skills=[skill.id],
    messages=[
        {
            "role": "user",
            "content": "Analyze this ticket: Customer reports login failures on mobile app"
        }
    ]
)

print(message.content)

Managing skills

List all skills

Retrieve all skills in your account:

skills = client.skills.list()

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

Get skill details

Retrieve information about a specific skill:

skill = client.skills.retrieve("skill_abc123")

print(f"Name: {skill.name}")
print(f"Description: {skill.description}")
print(f"Created: {skill.created_at}")

Update a skill

Modify an existing skill:

updated_skill = client.skills.update(
    skill_id="skill_abc123",
    description="Updated description with more triggering keywords"
)

Delete a skill

Remove a skill from your account:

client.skills.delete("skill_abc123")
print("Skill deleted")

Advanced: Skills with bundled resources

Skills can include scripts, reference documents, and assets for complex workflows.

Directory structure

customer-support-analyzer/
├── SKILL.md                    # Main skill file (required)
├── scripts/
│   ├── categorize.py           # Classification logic
│   └── route.py                # Department routing
├── references/
│   ├── knowledge-base.md       # Common solutions
│   └── escalation-rules.md     # Severity guidelines
└── assets/
    └── response-templates.json # Template responses

Uploading skills with resources

When uploading via API, package the entire skill directory:

import tarfile
import io

# Create tarball of skill directory
tar_buffer = io.BytesIO()
with tarfile.open(fileobj=tar_buffer, mode='w:gz') as tar:
    tar.add('customer-support-analyzer/', arcname='.')

tar_buffer.seek(0)

# Upload skill with resources
skill = client.skills.create(
    name="customer-support-analyzer",
    description="Analyze support tickets with categorization and routing",
    content=tar_buffer.read(),
    content_type="application/gzip"
)

Referencing bundled resources

In your SKILL.md, guide Claude to use bundled resources:

## Classification Process

When categorizing tickets:

1. Run `scripts/categorize.py` with the ticket description
2. Consult `references/knowledge-base.md` for similar issues
3. Apply escalation rules from `references/escalation-rules.md`
4. Use response template from `assets/response-templates.json`

### Example

```python
# Execute classification script
result = bash("python scripts/categorize.py 'Login failure on mobile'")
category = result.stdout.strip()

## Best practices

### Optimize skill descriptions for triggering

Skill descriptions determine when Claude activates a skill. Write comprehensive descriptions:

```yaml
# Less effective
description: Analyze customer support tickets

# More effective
description: Analyze customer support tickets and categorize issues by type, 
  severity, and department. Use when processing support ticket data, analyzing 
  customer feedback patterns, routing tickets, generating support reports, or 
  identifying common customer issues. Also use when mentions of tickets, 
  customer complaints, support queries, or help desk data appear.

Keep SKILL.md focused

Aim for under 500 lines in the main file. Use progressive disclosure:

1. Metadata (name + description): Always in context (~100 words)
2. SKILL.md body: Loaded when skill triggers (<500 lines)
3. Bundled resources: Loaded as needed (unlimited size)

For large reference material, split into separate files:

## Reference Documentation

For detailed information:
- Common issues: See `references/knowledge-base.md`
- Escalation procedures: See `references/escalation-rules.md`
- API integration: See `references/api-guide.md`

Test skills thoroughly

Create test cases covering different phrasings and edge cases:

test_cases = [
    "Analyze ticket T-12345",
    "Customer can't log in on mobile",
    "Categorize this support issue: billing error",
    "What department should handle payment processing bugs?"
]

for test in test_cases:
    message = client.messages.create(
        model="claude-4.5-sonnet",
        max_tokens=1024,
        skills=[skill.id],
        messages=[{"role": "user", "content": test}]
    )
    print(f"Test: {test}")
    print(f"Response: {message.content}\n")

Version your skills

Include version information in skill metadata:

---
name: customer-support-analyzer
version: 2.1.0
description: Analyze and categorize customer support tickets (v2.1.0)
last_updated: 2026-03-02
---

Error handling

Handle common errors when working with the Skills API:

try:
    skill = client.skills.create(
        name="my-skill",
        description="Skill description",
        content=skill_content
    )
except anthropic.APIError as e:
    if e.status_code == 400:
        print("Invalid skill format:", e.message)
    elif e.status_code == 409:
        print("Skill with this name already exists")
    else:
        print(f"API error: {e}")

Rate limits and quotas

• Skills API calls count toward your standard API rate limits
• Each account has a quota for total stored skills (contact support for limits)
• Skill content size is limited to 10MB per skill (including all bundled resources)

Additional resources

• Skills API Reference
• Creating custom skills
• Agent Skills specification
• Anthropic skills repository