> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="Create a skill">
    Upload a skill to your account:

    ```python theme={null}
    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}")
    ```
  </Step>

  <Step title="Use the skill in a message">
    Reference the skill in your API calls:

    ```python theme={null}
    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)
    ```
  </Step>
</Steps>

<Note>
  For complete API documentation and examples, see the [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide#creating-a-skill) in the Claude API documentation.
</Note>

## 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

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="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
  </Tab>

  <Tab title="Creative & design">
    * **algorithmic-art**: Generate procedural graphics
    * **canvas-design**: Create visual layouts
    * **frontend-design**: Build UI components
    * **theme-factory**: Develop visual themes
  </Tab>
</Tabs>

### Referencing pre-built skills

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

```python theme={null}
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:

```markdown theme={null}
---
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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  import Anthropic from '@anthropic-ai/sdk';
  import fs from 'fs';

  const client = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY,
  });

  // Read skill file
  const skillContent = fs.readFileSync('skills/customer-support/SKILL.md', 'utf-8');

  // Create skill
  const skill = await client.skills.create({
    name: 'customer-support-analyzer',
    description: 'Analyze and categorize customer support tickets',
    content: skillContent,
  });

  console.log(`Skill created: ${skill.id}`);

  // Use the skill
  const message = await 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',
      },
    ],
  });

  console.log(message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.anthropic.com/v1/skills \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "content-type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "name": "customer-support-analyzer",
      "description": "Analyze and categorize customer support tickets",
      "content": "---\nname: customer-support-analyzer\ndescription: Analyze support tickets...\n---\n\n# Customer Support Analyzer\n..."
    }'
  ```
</CodeGroup>

## Managing skills

### List all skills

Retrieve all skills in your account:

```python theme={null}
skills = client.skills.list()

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

### Get skill details

Retrieve information about a specific skill:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

````markdown theme={null}
## 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:

```markdown theme={null}
## 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:

```python theme={null}
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:

```yaml theme={null}
---
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:

```python theme={null}
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

<Note>
  * 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)
</Note>

## Additional resources

* [Skills API Reference](https://docs.claude.com/en/api/skills-guide)
* [Creating custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
* [Agent Skills specification](https://agentskills.io/specification)
* [Anthropic skills repository](https://github.com/anthropics/skills)