skills-guide changedbuild-with-claude/skills-guide
Nearest release: v2.1.232, published 7 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+4,966added
Lines−0removed
From line
—
no hunk to open at
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
## Quick links ## Overview ### Using Skills ### Prerequisites ## Using Skills in Messages ### Container parameter ### Downloading generated files ### Multi-turn conversations ### Long-running operations ### Using multiple Skills ## Managing custom Skills ### Creating a Skill ### Listing Skills ### Retrieving a Skill ### Deleting a Skill ### Versioning ## How Skills are loaded ## Use cases ### Example: financial modeling ## Limits and constraints ### Request limits ### Environment constraints ## Best practices ### When to use multiple Skills ### Version management strategy ### Prompt caching considerations ### Error handling ## Data retention ## Next steps
The whole hunk
4966 lines, first recorded
/
lines
The first capture of this source. The page was already there, and this is what it said.
---
title: Using Agent Skills with the API
url: https://platform.claude.com/docs/en/build-with-claude/skills-guide
description: Learn how to use Agent Skills to extend Claude's capabilities through 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.
<Note>
For complete API reference including request/response schemas and all parameters, see:
* [Skill Management API Reference](https://platform.claude.com/docs/en/api/beta/skills/list) - CRUD operations for Skills
* [Skill Versions API Reference](https://platform.claude.com/docs/en/api/beta/skills/versions/list) - Version management
</Note>
<Note>
For how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
</Note>
## Quick links
<CardGroup cols={2}>
<Card title="Get started with Agent Skills in the API" icon="rocket" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart">
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
</Card>
<Card title="Skill authoring best practices" icon="hammer" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices">
Learn how to write effective Skills that Claude can discover and use successfully.
</Card>
</CardGroup>
## Overview
<Note>
For a detailed look at the architecture and real-world applications of Agent Skills, read the engineering blog post: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
</Note>
Skills integrate with the Messages API through the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/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 run in the code execution environment.
You can use Skills from two sources:
| Aspect | Anthropic Skills | Custom Skills |
| ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Type value** | `anthropic` | `custom` |
| **Skill IDs** | Short names: `pptx`, `xlsx`, `docx`, `pdf` | Generated: `skill_01AbCdEfGhIjKlMnOpQrStUv` |
| **Version format** | Date-based: `20251013` or `latest` | Epoch timestamp: `1759178010641129` or `latest` |
| **Management** | Pre-built and maintained by Anthropic | Upload and manage through the [Skills API](https://platform.claude.com/docs/en/api/beta/skills/create) |
| **Availability** | Available to all users | Private to your workspace |
Both skill sources are returned by the [List Skills endpoint](https://platform.claude.com/docs/en/api/beta/skills/list) (use the `source` parameter to filter). The integration shape and execution environment are identical. The only difference is where the Skills come from and how they're managed.
### Prerequisites
To use Skills, you need:
1. **Claude API key** from the [Claude Console](https://platform.claude.com/settings/keys)
2. **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` - Required only when you use the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) to upload input files or download files a Skill produces
3. **[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** enabled in your requests
Skills require the code execution tool, so use a model from its [model compatibility list](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#model-compatibility).
***
## Using Skills in Messages
### Container parameter
Skills are specified using the `container` parameter in the Messages API. You can include up to 8 Skills for each 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:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a presentation about renewable energy"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25,skills-2025-10-02 <<'YAML'
model: claude-opus-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
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"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-opus-5",
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"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = "claude-opus-5",
MaxTokens = 4096,
Betas = ["code-execution-2025-08-25", "skills-2025-10-02"],
Container = new BetaContainerParams
{
Skills =
[
new BetaSkillParams
{
Type = BetaSkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a presentation about renewable energy" }],
Tools = [new BetaCodeExecutionTool20250825()],
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-5",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaSkills2025_10_02,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a presentation about renewable energy")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build())
.build())
.addUserMessage("Create a presentation about renewable energy")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation about renewable energy']
],
model: 'claude-opus-5',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
[
'type' => 'anthropic',
'skill_id' => 'pptx',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.beta.messages.create(
Cut at 300 lines. The page has the rest.
No line in this hunk matches that.