---
title: Usando Agent Skills com a API
url: https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide
description: Aprenda a usar Agent Skills para estender as capacidades do Claude por meio da API.
---
Agent Skills estendem as capacidades do Claude por meio de pastas organizadas de instruções, scripts e recursos. Este guia mostra como usar tanto Skills pré-construídas quanto Skills personalizadas com a Claude API.
Para a referência completa da API, incluindo esquemas de requisição/resposta e todos os parâmetros, consulte:
* [Referência da API de gerenciamento de Skills](https://platform.claude.com/docs/pt-BR/api/skills/list) - Operações CRUD para Skills
* [Referência da API de versões de Skills](https://platform.claude.com/docs/pt-BR/api/skills/versions/list) - Gerenciamento de versões
Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
## Links rápidos
Aprenda a usar Agent Skills para criar documentos com a Claude API em menos de 10 minutos.
Aprenda a escrever Skills eficazes que o Claude consiga descobrir e usar com sucesso.
## Visão geral
Para uma análise detalhada da arquitetura e das aplicações reais de Agent Skills, leia o post do blog de engenharia: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
As Skills se integram à Messages API por meio da [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) ("code execution tool"). Seja usando Skills pré-construídas gerenciadas pela Anthropic ou Skills personalizadas que você enviou, o formato de integração é idêntico: ambas exigem execução de código e usam a mesma estrutura `container`.
### Usando Skills
As Skills se integram de forma idêntica na Messages API, independentemente da origem. Você especifica as Skills no parâmetro `container` com um `skill_id`, `type` e um `version` opcional, e elas são executadas no ambiente de execução de código.
Você pode usar Skills de duas origens:
| Aspecto | Skills da Anthropic | Skills personalizadas |
| --------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Valor de type** | `anthropic` | `custom` |
| **IDs de Skill** | Nomes curtos: `pptx`, `xlsx`, `docx`, `pdf` | Gerados: `skill_01AbCdEfGhIjKlMnOpQrStUv` |
| **Formato de versão** | Baseado em data: `20251013` ou `latest` | ID de versão: `skver_01AbCdEfGhIjKlMnOpQrStUv` ou `latest` |
| **Gerenciamento** | Pré-construídas e mantidas pela Anthropic | Envie e gerencie por meio da [Skills API](https://platform.claude.com/docs/pt-BR/api/skills/create) |
| **Disponibilidade** | Disponíveis para todos os usuários | Privadas ao seu workspace |
Ambas as origens de skills são retornadas pelo [endpoint List Skills](https://platform.claude.com/docs/pt-BR/api/skills/list) (use o parâmetro `source` para filtrar). O formato de integração e o ambiente de execução são idênticos. A única diferença é de onde as Skills vêm e como são gerenciadas.
### Pré-requisitos
Para usar Skills, você precisa de:
1. **Chave de API do Claude** obtida no [Claude Console](https://platform.claude.com/settings/keys)
2. **[Ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool)** habilitada em suas requisições
As Skills exigem a ferramenta de execução de código, portanto use um modelo da sua [lista de compatibilidade de modelos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#compatibility).
***
## Usando Skills em Messages
### Parâmetro container
As Skills são especificadas usando o parâmetro `container` na Messages API. Você pode incluir até 20 Skills em cada requisição.
A estrutura é idêntica tanto para Skills da Anthropic quanto para Skills personalizadas. Especifique os campos obrigatórios `type` e `skill_id` e, opcionalmente, inclua `version` para fixar uma versão específica:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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 messages create <<'YAML'
model: claude-opus-5-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.messages.create(
model="claude-opus-5-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"}],
)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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"
}
]
});
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a presentation about renewable energy" }],
Tools = [new CodeExecutionTool20250825()],
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a presentation about renewable energy")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build())
.build())
.addUserMessage("Create a presentation about renewable energy")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation about renewable energy']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'anthropic',
'skillID' => 'pptx',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
]
)
puts message
```
### Baixando arquivos gerados
Quando as Skills criam documentos (Excel, PowerPoint, PDF, Word), elas retornam atributos `file_id` na resposta. Você deve usar a Files API para baixar esses arquivos.
**Como funciona:**
1. As Skills criam arquivos durante a execução de código.
2. A resposta inclui um `file_id` para cada arquivo criado, dentro dos blocos de resultado da ferramenta de execução de código (consulte [Formato de resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#response-format)).
3. Use a Files API para baixar o conteúdo real do arquivo.
4. Salve localmente ou processe conforme necessário.
Para fornecer arquivos de entrada para as Skills trabalharem, [envie-os com a Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files#uploading-a-file) e referencie-os em sua requisição com um [bloco de upload de container](https://platform.claude.com/docs/pt-BR/build-with-claude/files#container-upload-blocks).
**Exemplo: criando e baixando um arquivo Excel**
```bash cURL
# Etapa 1: Use uma Skill para criar um arquivo
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
"messages": [{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}')
# Etapa 2: Extraia o file_id da resposta (usando jq)
FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="bash_code_execution_tool_result") | .content | select(.type=="bash_code_execution_result") | .content[] | select(.file_id) | .file_id')
# Etapa 3: Obtenha o nome do arquivo a partir dos metadados
FILENAME=$(curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" | jq -r '.filename')
# Etapa 4: Baixe o arquivo usando a Files API
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
--output "$FILENAME"
echo "Downloaded: $FILENAME"
```
```bash CLI
# Passo 1: Use a Skill xlsx para criar um arquivo
# Passo 2: Extraia o file_id da resposta com --transform (caminho GJSON)
FILE_ID=$(ant messages create \
--transform 'content.#.content.content.#.file_id|@flatten|0' \
--raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Create an Excel file with a simple budget spreadsheet
tools:
- type: code_execution_20250825
name: code_execution
YAML
)
# Passo 3: Obtenha o nome do arquivo a partir dos metadados do arquivo
FILENAME=$(ant files retrieve-metadata \
--file-id "$FILE_ID" \
--transform filename \
--raw-output)
# Passo 4: Baixe o arquivo usando a Files API
ant files download --file-id "$FILE_ID" --output "$FILENAME" > /dev/null
printf 'Downloaded: %s\n' "$FILENAME"
```
```python Python
client = anthropic.Anthropic()
# Passo 1: Use uma Skill para criar um arquivo
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Passo 2: Extraia os IDs de arquivo da resposta
def extract_file_ids(response):
file_ids = []
for item in response.content:
if item.type == "bash_code_execution_tool_result":
content_item = item.content
if content_item.type == "bash_code_execution_result":
# cada item de conteúdo é um bloco bash_code_execution_output que contém um file_id
for file in content_item.content:
file_ids.append(file.file_id)
return file_ids
# Passo 3: Baixe o arquivo usando a Files API
for file_id in extract_file_ids(response):
file_metadata = client.files.retrieve_metadata(file_id=file_id)
file_content = client.files.download(file_id=file_id)
# Passo 4: Salve no disco
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")
```
```typescript TypeScript
import { writeFile } from "node:fs/promises";
const client = new Anthropic();
// Passo 1: Use uma Skill para criar um arquivo
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{
role: "user",
content: "Create an Excel file with a simple budget spreadsheet"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Passo 2: Extraia os IDs de arquivo da resposta
const fileIds: string[] = [];
for (const block of response.content) {
if (
block.type === "bash_code_execution_tool_result" &&
block.content.type === "bash_code_execution_result"
) {
for (const outputBlock of block.content.content) {
fileIds.push(outputBlock.file_id);
}
}
}
// Passo 3: Baixe cada arquivo e salve no disco
for (const fileId of fileIds) {
const fileMetadata = await client.files.retrieveMetadata(fileId);
const fileResponse = await client.files.download(fileId);
await writeFile(fileMetadata.filename, Buffer.from(await fileResponse.arrayBuffer()));
console.log(`Downloaded: ${fileMetadata.filename}`);
}
```
```csharp C#
AnthropicClient client = new();
// Passo 1: Use uma Skill para criar um arquivo
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create an Excel file with a simple budget spreadsheet" }],
Tools = [new CodeExecutionTool20250825()],
};
var response = await client.Messages.Create(parameters);
// Passo 2: Extraia os IDs de arquivo da resposta
List fileIds = [];
foreach (var block in response.Content)
{
if (block.TryPickBashCodeExecutionToolResult(out var toolResult)
&& toolResult.Content.TryPickBashCodeExecutionResultBlock(out var result))
{
foreach (var output in result.Content)
{
fileIds.Add(output.FileID);
}
}
}
// Passo 3: Baixe cada arquivo e salve-o em disco
foreach (var fileId in fileIds)
{
var fileMetadata = await client.Files.RetrieveMetadata(fileId);
using var download = await client.Files.Download(fileId);
using var downloadStream = await download.ReadAsStream();
using var outputFile = File.Create(fileMetadata.Filename);
await downloadStream.CopyToAsync(outputFile);
Console.WriteLine($"Downloaded: {fileMetadata.Filename}");
}
```
```go Go
func main() {
client := anthropic.NewClient()
// Passo 1: Use uma Skill para criar um arquivo
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create an Excel file with a simple budget spreadsheet")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
// Passo 2: Extraia os IDs de arquivo da resposta
fileIDs := extractFileIDs(response)
// Passo 3: Baixe o arquivo usando a Files API
for _, fileID := range fileIDs {
fileMetadata, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
if err != nil {
log.Fatal(err)
}
fileContent, err := client.Files.Download(context.TODO(), fileID, anthropic.FileDownloadParams{})
if err != nil {
log.Fatal(err)
}
// Passo 4: Salve no disco
out, err := os.Create(fileMetadata.Filename)
if err != nil {
log.Fatal(err)
}
if _, err := io.Copy(out, fileContent.Body); err != nil {
log.Fatal(err)
}
out.Close()
fileContent.Body.Close()
fmt.Printf("Downloaded: %s\n", fileMetadata.Filename)
}
}
func extractFileIDs(response *anthropic.Message) []string {
var fileIDs []string
for _, item := range response.Content {
switch v := item.AsAny().(type) {
case anthropic.BashCodeExecutionToolResultBlock:
if v.Content.Type == "bash_code_execution_result" {
for _, output := range v.Content.Content {
fileIDs = append(fileIDs, output.FileID)
}
}
}
}
return fileIDs
}
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
import com.anthropic.models.messages.ContentBlock;
import com.anthropic.models.files.FileMetadata;
import com.anthropic.core.http.HttpResponse;
// ...
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Passo 1: Use uma Skill para criar um arquivo
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create an Excel file with a simple budget spreadsheet")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
// Passo 2: Extraia os IDs de arquivo da resposta
List fileIds = new ArrayList<>();
for (ContentBlock block : response.content()) {
if (block.isBashCodeExecutionToolResult()) {
var content = block.asBashCodeExecutionToolResult().content();
if (content.isBashCodeExecutionResultBlock()) {
for (var outputBlock : content.asBashCodeExecutionResultBlock().content()) {
fileIds.add(outputBlock.fileId());
}
}
}
}
// Passo 3: Baixe o arquivo usando a Files API
for (String fileId : fileIds) {
FileMetadata fileMetadata = client.files().retrieveMetadata(fileId);
HttpResponse fileContent = client.files().download(fileId);
// Passo 4: Salve no disco
try (InputStream is = fileContent.body();
FileOutputStream fos = new FileOutputStream(fileMetadata.filename())) {
is.transferTo(fos);
}
System.out.println("Downloaded: " + fileMetadata.filename());
}
}
```
```php PHP
$client = new Client();
// Etapa 1: Use uma Skill para criar um arquivo
$response = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create an Excel file with a simple budget spreadsheet']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
// Etapa 2: Extraia os IDs de arquivo da resposta
function extractFileIds($response) {
$fileIds = [];
foreach ($response->content as $item) {
if ($item->type === 'bash_code_execution_tool_result') {
$contentItem = $item->content;
if ($contentItem->type === 'bash_code_execution_result') {
foreach ($contentItem->content as $file) {
$fileIds[] = $file->fileID;
}
}
}
}
return $fileIds;
}
// Etapa 3: Baixe o arquivo usando a Files API
foreach (extractFileIds($response) as $fileId) {
$fileMetadata = $client->files->retrieveMetadata($fileId);
$fileContent = $client->files->download($fileId);
// Etapa 4: Salve no disco
file_put_contents($fileMetadata->filename, $fileContent);
echo "Downloaded: {$fileMetadata->filename}\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
# Passo 1: Use uma Skill para criar um arquivo
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{
role: "user",
content: "Create an Excel file with a simple budget spreadsheet"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
# Passo 2: Extraia os IDs de arquivo da resposta
def extract_file_ids(response)
file_ids = []
response.content.each do |item|
if item.type == :bash_code_execution_tool_result
content_item = item.content
if content_item.type == :bash_code_execution_result
content_item.content.each do |file|
file_ids << file.file_id
end
end
end
end
file_ids
end
# Passo 3: Baixe o arquivo usando a Files API
extract_file_ids(response).each do |file_id|
file_metadata = client.files.retrieve_metadata(file_id)
file_content = client.files.download(file_id)
# Passo 4: Salve no disco
File.binwrite(file_metadata.filename, file_content.read)
puts "Downloaded: #{file_metadata.filename}"
end
```
**Operações adicionais da Files API:**
```bash cURL
# Obter metadados do arquivo
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Listar todos os arquivos
curl "https://api.anthropic.com/v1/files" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Excluir um arquivo
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
# Obter metadados do arquivo
ant files retrieve-metadata \
--file-id "$FILE_ID" \
--transform '{filename,size_bytes}' \
--format yaml
# Listar todos os arquivos
ant files list --transform '{filename,created_at}' --format yaml
# Excluir um arquivo
ant files delete --file-id "$FILE_ID" >/dev/null
```
```python Python
client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obter metadados do arquivo
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# Listar todos os arquivos
for file in client.files.list():
print(f"{file.filename} - {file.created_at}")
# Excluir um arquivo
client.files.delete(file_id=file_id)
```
```typescript TypeScript
const client = new Anthropic();
const fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Obter metadados do arquivo
const fileInfo = await client.files.retrieveMetadata(fileId);
console.log(`Filename: ${fileInfo.filename}, Size: ${fileInfo.size_bytes} bytes`);
// Listar todos os arquivos
for await (const file of client.files.list()) {
console.log(`${file.filename} - ${file.created_at}`);
}
// Excluir um arquivo
await client.files.delete(fileId);
```
```csharp C#
AnthropicClient client = new();
var fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Obter metadados do arquivo
var fileInfo = await client.Files.RetrieveMetadata(fileId);
Console.WriteLine($"Filename: {fileInfo.Filename}, Size: {fileInfo.SizeBytes} bytes");
// Listar arquivos
await foreach (var file in (await client.Files.List()).Paginate())
{
Console.WriteLine($"{file.Filename} - {file.CreatedAt}");
}
// Excluir o arquivo
await client.Files.Delete(fileId);
```
```go Go
client := anthropic.NewClient()
fileID := "file_011CNha8iCJcU1wXNR6q4V8w"
// Obter os metadados do arquivo
fileInfo, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Filename: %s, Size: %d bytes\n", fileInfo.Filename, fileInfo.SizeBytes)
// Listar todos os arquivos
files := client.Files.ListAutoPaging(context.TODO(), anthropic.FileListParams{})
for files.Next() {
file := files.Current()
fmt.Printf("%s - %s\n", file.Filename, file.CreatedAt)
}
if files.Err() != nil {
log.Fatal(files.Err())
}
// Excluir um arquivo
_, err = client.Files.Delete(context.TODO(), fileID, anthropic.FileDeleteParams{})
if err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.files.FileMetadata;
import com.anthropic.models.files.FileListPage;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Obter metadados do arquivo
FileMetadata fileInfo = client.files().retrieveMetadata(fileId);
System.out.println("Filename: " + fileInfo.filename() + ", Size: " + fileInfo.sizeBytes() + " bytes");
// Listar arquivos (primeira página)
FileListPage files = client.files().list();
for (var file : files.data()) {
System.out.println(file.filename() + " - " + file.createdAt());
}
// Excluir um arquivo
client.files().delete(fileId);
}
```
```php PHP
$client = new Client();
$fileId = 'file_011CNha8iCJcU1wXNR6q4V8w';
// Obter metadados do arquivo
$fileInfo = $client->files->retrieveMetadata($fileId);
echo "Filename: {$fileInfo->filename}, Size: {$fileInfo->sizeBytes} bytes\n";
// Listar arquivos (primeira página)
foreach ($client->files->list()->getItems() as $file) {
echo "{$file->filename} - {$file->createdAt->format(DATE_ATOM)}\n";
}
// Excluir um arquivo
$client->files->delete($fileId);
```
```ruby Ruby
client = Anthropic::Client.new
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obter metadados do arquivo
file_info = client.files.retrieve_metadata(file_id)
puts "Filename: #{file_info.filename}, Size: #{file_info.size_bytes} bytes"
# Listar todos os arquivos
client.files.list.auto_paging_each do |file|
puts "#{file.filename} - #{file.created_at}"
end
# Excluir um arquivo
client.files.delete(file_id)
```
Para detalhes completos, consulte [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files).
### Conversas de múltiplos turnos
O objeto `container` da resposta traz o `id` do container e o timestamp `expires_at` (consulte [Reutilização de container](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse) para detalhes sobre o tempo de vida). Reutilize o mesmo container em várias mensagens especificando o ID do container:
A reutilização de container em múltiplos turnos exige mais lógica do que um único comando de shell, então use o Claude SDK para isso. Para montar as requisições você mesmo, capture `container.id` da primeira resposta. Em seguida, passe-o na próxima requisição como `"container": {"id": "...", "skills": [...]}`, junto com o histórico da conversa.
```bash CLI
# A primeira requisição cria o contêiner
CONTAINER_ID=$(ant messages create \
--transform container.id \
--raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- {type: anthropic, skill_id: xlsx, version: latest}
messages:
- role: user
content: Create a sample sales dataset and analyze it
tools:
- {type: code_execution_20250825, name: code_execution}
YAML
)
# Continua a conversa com o mesmo contêiner
ant messages create < block.type === "text")
.map((block) => block.text)
.join("\n")
},
{ role: "user", content: "What was the total revenue?" }
];
const response2 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
id: response1.container!.id, // Reuse container
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C#
AnthropicClient client = new();
// Primeira requisição com uma Skill
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a sample sales dataset and analyze it" }],
Tools = [new CodeExecutionTool20250825()],
};
var response1 = await client.Messages.Create(parameters1);
// Continue a conversa no mesmo contêiner
// Repasse o texto do assistente; container.id carrega o estado de execução
var assistantText = string.Join(
"\n",
response1.Content.Select(block => block.TryPickText(out var text) ? text.Text : null).Where(text => text is not null)
);
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
ID = response1.Container!.ID,
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages =
[
new() { Role = Role.User, Content = "Create a sample sales dataset and analyze it" },
new() { Role = Role.Assistant, Content = assistantText },
new() { Role = Role.User, Content = "What was the total revenue?" },
],
Tools = [new CodeExecutionTool20250825()],
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine(response2);
```
```go Go
client := anthropic.NewClient()
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a sample sales dataset and analyze it")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
// Leve o texto do assistente adiante; container.id carrega o estado da execução
var textParts []string
for _, block := range response1.Content {
if block.Type == "text" {
textParts = append(textParts, block.Text)
}
}
assistantText := strings.Join(textParts, "\n")
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
ID: anthropic.String(response1.Container.ID), // Reuse container
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a sample sales dataset and analyze it")),
{
Role: anthropic.MessageParamRoleAssistant,
Content: []anthropic.ContentBlockParamUnion{anthropic.NewTextBlock(assistantText)},
},
anthropic.NewUserMessage(anthropic.NewTextBlock("What was the total revenue?")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response2)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
import com.anthropic.models.messages.ContentBlock;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create a sample sales dataset and analyze it")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response1 = client.messages().create(params1);
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.id(response1.container().get().id())
.addSkill(SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create a sample sales dataset and analyze it")
// Leve o texto do assistente adiante; container.id carrega o estado da execução
.addAssistantMessage(response1.content().stream()
.filter(ContentBlock::isText)
.map(block -> block.asText().text())
.collect(Collectors.joining("\n")))
.addUserMessage("What was the total revenue?")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response2 = client.messages().create(params2);
System.out.println(response2);
}
```
```php PHP
$client = new Client();
$response1 = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a sample sales dataset and analyze it']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
$messages = [
['role' => 'user', 'content' => 'Create a sample sales dataset and analyze it'],
// Leve o texto do assistente adiante; container.id carrega o estado da execução
['role' => 'assistant', 'content' => implode("\n", array_map(
fn ($block) => $block->text,
array_filter($response1->content, fn ($block) => $block->type === 'text'),
))],
['role' => 'user', 'content' => 'What was the total revenue?']
];
$response2 = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
container: [
'id' => $response1->container->id,
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response2;
```
```ruby Ruby
client = Anthropic::Client.new
response1 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{ role: "user", content: "Create a sample sales dataset and analyze it" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
messages = [
{ role: "user", content: "Create a sample sales dataset and analyze it" },
{
# Leve o texto do assistente adiante; container.id carrega o estado da execução
role: "assistant",
content: response1.content.filter_map { |block| block.text if block.type == :text }.join("\n")
},
{ role: "user", content: "What was the total revenue?" }
]
response2 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
id: response1.container.id,
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" }
]
},
messages: messages,
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts response2
```
### Operações de longa duração
As Skills podem realizar operações que exigem múltiplos turnos. Trate os motivos de parada `pause_turn`:
```bash cURL
# Requisição inicial
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Generate and process a large sample dataset"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}')
# Se stop_reason for "pause_turn", continue no mesmo contêiner, anexando
# o array content da resposta anterior a messages como o turno do assistente.
# Repita esta requisição de continuação até que stop_reason não seja mais "pause_turn".
STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason')
CONTAINER_ID=$(echo "$RESPONSE" | jq -r '.container.id')
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-5-5\",
\"max_tokens\": 4096,
\"container\": {
\"id\": \"$CONTAINER_ID\",
\"skills\": [{
\"type\": \"custom\",
\"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
\"version\": \"latest\"
}]
},
\"messages\": [],
\"tools\": [{
\"type\": \"code_execution_20250825\",
\"name\": \"code_execution\"
}]
}")
```
```bash CLI
RESP=$(mktemp)
# Requisição inicial: salva a resposta JSON completa em um arquivo temporário
ant messages create > "$RESP" <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Generate and process a large sample dataset
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Se stop_reason for "pause_turn", continue no mesmo contêiner,
# anexando o array content da resposta anterior a messages como o
# turno do assistente. Repita até que stop_reason não seja mais "pause_turn".
CONTAINER_ID=$(jq -r '.container.id' "$RESP")
ant messages create > "$RESP" < messages =
[
new() { Role = Role.User, Content = "Generate and process a large sample dataset" },
];
var maxRetries = 10;
string? containerId = null;
Message? response = null;
for (var i = 0; i < maxRetries; i++)
{
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = containerId is null
? new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
}
: new ContainerParams
{
ID = containerId,
Skills =
[
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
},
Messages = messages,
Tools = [new CodeExecutionTool20250825()],
};
response = await client.Messages.Create(parameters);
containerId = response.Container!.ID;
if (response.StopReason != StopReason.PauseTurn)
{
break;
}
// Anexa o conteúdo do turno pausado e continua
var assistantContent = JsonSerializer.SerializeToElement(
response.Content.Select(block => block.Json).ToArray()
);
messages.Add(new() { Role = Role.Assistant, Content = new MessageParamContent(assistantContent) });
}
```
```go Go
client := anthropic.NewClient()
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Generate and process a large sample dataset")),
}
maxRetries := 10
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: messages,
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
for i := 0; i < maxRetries; i++ {
if response.StopReason != anthropic.StopReasonPauseTurn {
break
}
messages = append(messages, response.ToParam())
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
ID: anthropic.String(response.Container.ID), // Reuse container
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: messages,
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
import com.anthropic.models.messages.StopReason;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List messages = new ArrayList<>();
messages.add(
MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Generate and process a large sample dataset")
.build()
);
int maxRetries = 10;
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.messages(messages)
.addTool(CodeExecutionTool20250825.builder().build())
.build());
for (int i = 0; i < maxRetries; i++) {
if (!response.stopReason().isPresent()
|| !response.stopReason().get().equals(StopReason.PAUSE_TURN)) {
break;
}
messages.add(response.toParam());
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.id(response.container().get().id())
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.messages(messages)
.addTool(CodeExecutionTool20250825.builder().build())
.build());
}
}
```
```php PHP
$client = new Client();
$messages = [
['role' => 'user', 'content' => 'Generate and process a large sample dataset']
];
$maxRetries = 10;
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
for ($i = 0; $i < $maxRetries; $i++) {
if ($response->stopReason !== 'pause_turn') {
break;
}
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
container: [
'id' => $response->container->id,
'skills' => [
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
}
```
```ruby Ruby
client = Anthropic::Client.new
messages = [
{ role: "user", content: "Generate and process a large sample dataset" }
]
max_retries = 10
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
max_retries.times do
break if response.stop_reason != :pause_turn
messages << { role: "assistant", content: response.content }
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
id: response.container.id,
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
end
```
A resposta pode incluir um motivo de parada `pause_turn`, que indica que a API pausou uma operação de Skill de longa duração. Você pode fornecer a resposta de volta como está em uma requisição subsequente para permitir que o Claude continue seu turno, ou modificar o conteúdo se quiser interromper a conversa e fornecer orientação adicional.
### Usando múltiplas Skills
Combine múltiplas Skills em uma única requisição para lidar com fluxos de trabalho complexos:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Analyze sales data and create a presentation"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: anthropic
skill_id: pptx
version: latest
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Analyze sales data and create a presentation
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
},
]
},
messages=[
{"role": "user", "content": "Analyze sales data and create a presentation"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
},
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
},
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Analyze sales data and create a presentation"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Analyze sales data and create a presentation" }],
Tools = [new CodeExecutionTool20250825()],
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze sales data and create a presentation")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build()
))
.build())
.addUserMessage("Analyze sales data and create a presentation")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze sales data and create a presentation']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'anthropic',
'skillID' => 'xlsx',
'version' => 'latest'
],
[
'type' => 'anthropic',
'skillID' => 'pptx',
'version' => 'latest'
],
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
},
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
},
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [
{ role: "user", content: "Analyze sales data and create a presentation" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts message
```
***
## Gerenciando Skills personalizadas
**As Skills personalizadas são acessíveis a todo o seu workspace, não têm escopo restrito a um usuário final, conversa ou sessão.** Qualquer chave de API com acesso a um workspace pode ler, invocar e excluir todas as Skills personalizadas enviadas a esse workspace. Toda conta de serviço, e todo usuário cuja função na organização permita acesso à API, pode usar o Default Workspace além de qualquer workspace ao qual você os adicione; portanto, mantenha as Skills que precisam ficar separadas em seu próprio [workspace](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#api-keys-and-resource-scoping) e acesse-as apenas com chaves com escopo restrito a esse workspace.
Se você está construindo uma plataforma multi-tenant sobre a Skills API, crie um [workspace](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces) separado para cada tenant. O workspace é a fronteira de isolamento para Skills personalizadas, portanto um workspace por tenant dá às Skills de cada tenant isolamento rígido em relação a todos os outros tenants. Cada organização pode ter até 100 workspaces por padrão (consulte [Como os workspaces funcionam](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#how-workspaces-work)); se você precisar de mais para isolamento de tenants, entre em contato com sua equipe de conta.
### Criando uma Skill
Um pacote de Skill é um diretório contendo um arquivo `SKILL.md` no nível superior com frontmatter YAML `name` e `description`, além de quaisquer scripts ou recursos de apoio. Consulte [Comece a usar Agent Skills na API](https://platform.claude.com/docs/pt-BR/agents-and-tools/agent-skills/quickstart) para criar uma, e a lista de **Requisitos** após os exemplos para as restrições completas.
Envie sua Skill personalizada para disponibilizá-la no seu workspace. Você pode enviar um arquivo zip ou objetos de arquivo individuais. O SDK Python também oferece um helper `files_from_dir` que aceita um caminho de diretório, e o `ant apply` da CLI envia o próprio diretório.
Os arquivos são identificados pelo nome de arquivo que você anexa (o sufixo `;filename=` no exemplo cURL e os argumentos de nome de arquivo nos exemplos de SDK). Para a skill do passo a passo, crie um zip com `zip -r financial_skill.zip financial_skill/` e substitua-o pelo placeholder `example_skill.zip` nas opções de upload de zip.
```bash cURL
curl -X POST "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
-F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py"
```
```bash CLI
ant apply financial_skill
```
```markdown
---
name: financial-skill
description: Docs example skill.
---
```
```python
print("financial analysis helper")
```
```python Python
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
# Opção 1: usando um arquivo zip
skill = client.skills.create(
files=[open("example_skill.zip", "rb")],
)
# Opção 2: usando tuplas de arquivo (filename, file_content, mime_type)
skill = client.skills.create(
files=[
(
"financial_skill/SKILL.md",
open("financial_skill/SKILL.md", "rb"),
"text/markdown",
),
(
"financial_skill/analyze.py",
open("financial_skill/analyze.py", "rb"),
"text/x-python",
),
],
)
# Opção 3: usando o helper files_from_dir (somente Python)
skill = client.skills.create(
files=files_from_dir("financial_skill"),
)
print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version_id}")
```
```typescript TypeScript
import { toFile } from "@anthropic-ai/sdk";
import fs from "node:fs";
// ...
const client = new Anthropic();
// Opção 1: usando um arquivo zip
const skillFromZip = await client.skills.create({
files: [await toFile(fs.createReadStream("example_skill.zip"), "example_skill.zip")]
});
// Opção 2: usando objetos de arquivo individuais
const skill = await client.skills.create({
files: [
await toFile(fs.createReadStream("financial_skill/SKILL.md"), "financial_skill/SKILL.md", {
type: "text/markdown"
}),
await toFile(
fs.createReadStream("financial_skill/analyze.py"),
"financial_skill/analyze.py",
{ type: "text/x-python" }
)
]
});
console.log(`Created skill: ${skill.id}`);
console.log(`Latest version: ${skill.latest_version_id}`);
```
```csharp C#
using Anthropic.Core;
// ...
AnthropicClient client = new();
// Opção 1: usando um arquivo zip
var parameters = new SkillCreateParams
{
Files = [File.OpenRead("example_skill.zip")],
};
var skill = await client.Skills.Create(parameters);
// Opção 2: usando arquivos individuais (nomes de arquivo qualificados por caminho preservam o layout de diretórios da Skill)
var parameters2 = new SkillCreateParams
{
Files =
[
new BinaryContent
{
Stream = File.OpenRead("financial_skill/SKILL.md"),
FileName = "financial_skill/SKILL.md",
},
new BinaryContent
{
Stream = File.OpenRead("financial_skill/analyze.py"),
FileName = "financial_skill/analyze.py",
},
],
};
var skill2 = await client.Skills.Create(parameters2);
Console.WriteLine($"Created skill: {skill.ID}");
Console.WriteLine($"Latest version: {skill.LatestVersionID}");
Console.WriteLine($"Created skill 2: {skill2.ID}");
```
```go Go
client := anthropic.NewClient()
// Opção 1: usando um arquivo zip
zipFile, err := os.Open("example_skill.zip")
if err != nil {
log.Fatal(err)
}
defer zipFile.Close()
skill, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
Files: []io.Reader{zipFile},
})
if err != nil {
log.Fatal(err)
}
// Opção 2: usando arquivos individuais
skillMd, err := os.Open("financial_skill/SKILL.md")
if err != nil {
log.Fatal(err)
}
defer skillMd.Close()
analyzePy, err := os.Open("financial_skill/analyze.py")
if err != nil {
log.Fatal(err)
}
defer analyzePy.Close()
skill2, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
Files: []io.Reader{
anthropic.File(skillMd, "financial_skill/SKILL.md", "text/markdown"),
anthropic.File(analyzePy, "financial_skill/analyze.py", "text/x-python"),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created skill: %s\n", skill.ID)
fmt.Printf("Latest version: %s\n", skill.LatestVersionID)
fmt.Printf("Created skill 2: %s\n", skill2.ID)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.skills.SkillCreateParams;
import com.anthropic.models.skills.Skill;
// ...
void main() throws Exception {
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Opção 1: usando um arquivo zip
SkillCreateParams params = SkillCreateParams.builder()
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("example_skill.zip")))
.filename("example_skill.zip")
.contentType("application/zip")
.build())
.build();
Skill skill = client.skills().create(params);
// Opção 2: usando arquivos individuais (nomes de arquivo qualificados por caminho preservam o layout de diretórios da Skill)
SkillCreateParams params2 = SkillCreateParams.builder()
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("financial_skill/SKILL.md")))
.filename("financial_skill/SKILL.md")
.contentType("text/markdown")
.build())
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("financial_skill/analyze.py")))
.filename("financial_skill/analyze.py")
.contentType("text/x-python")
.build())
.build();
Skill skill2 = client.skills().create(params2);
System.out.println("Created skill: " + skill.id());
System.out.println("Latest version: " + skill.latestVersionId());
System.out.println("Created skill 2: " + skill2.id());
}
```
```php PHP
use Anthropic\Core\FileParam;
// ...
$client = new Client();
// Opção 1: usando um arquivo zip
$skill = $client->skills->create(
files: [
FileParam::fromResource(fopen('example_skill.zip', 'r')),
],
);
// Opção 2: usando arquivos individuais
$skill = $client->skills->create(
files: [
FileParam::fromResource(
fopen('financial_skill/SKILL.md', 'r'),
filename: 'financial_skill/SKILL.md',
contentType: 'text/markdown',
),
FileParam::fromResource(
fopen('financial_skill/analyze.py', 'r'),
filename: 'financial_skill/analyze.py',
contentType: 'text/x-python',
),
],
);
echo "Created skill: {$skill->id}\n";
echo "Latest version: {$skill->latestVersionID}\n";
```
```ruby Ruby
client = Anthropic::Client.new
# Opção 1: Usando um arquivo zip
skill = client.skills.create(
files: [
File.open("example_skill.zip", "rb")
]
)
# Opção 2: Usando arquivos individuais
skill = client.skills.create(
files: [
Anthropic::FilePart.new(
Pathname("financial_skill/SKILL.md"),
filename: "financial_skill/SKILL.md",
content_type: "text/markdown"
),
Anthropic::FilePart.new(
Pathname("financial_skill/analyze.py"),
filename: "financial_skill/analyze.py",
content_type: "text/x-python"
)
]
)
puts "Created skill: #{skill.id}"
puts "Latest version: #{skill.latest_version_id}"
```
**Requisitos:**
* Deve incluir um arquivo `SKILL.md` na raiz do upload (ou no topo de uma única pasta envolvente)
* `display_name` é opcional: quando omitido, é derivado do `name` do `SKILL.md`; um valor explícito pode ter até 255 caracteres e não precisa ser único dentro do workspace
* O tamanho total do upload deve ser inferior a 30 MB (descompactado)
* Requisitos do frontmatter YAML:
* `name`: Máximo de 64 caracteres, apenas letras minúsculas/números/hífens, sem tags XML, sem palavras reservadas ("anthropic", "claude")
* `description`: Máximo de 1024 caracteres, não vazio, sem tags XML
Para esquemas completos de requisição/resposta, consulte a [referência da API Create Skill](https://platform.claude.com/docs/pt-BR/api/skills/create).
### Listando Skills
Recupere todas as Skills disponíveis para seu workspace, incluindo tanto as Skills pré-construídas da Anthropic quanto suas Skills personalizadas. Use o parâmetro `source` para filtrar por tipo de skill:
```bash cURL
# Listar todas as Skills
curl "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# Listar apenas as Skills personalizadas
curl "https://api.anthropic.com/v1/skills?source=custom" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
# Listar todas as Skills
ant skills list
# Listar apenas Skills personalizadas
ant skills list --source custom
```
```python Python
client = anthropic.Anthropic()
# Listar todas as Skills
for skill in client.skills.list():
print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")
# Listar apenas Skills personalizadas
custom_skills = client.skills.list(source="custom")
```
```typescript TypeScript
const client = new Anthropic();
// Listar todas as Skills
for await (const skill of client.skills.list()) {
console.log(`${skill.id}: ${skill.display_name} (source: ${skill.source.type})`);
}
// Listar apenas Skills personalizadas
const customSkills = await client.skills.list({
source: "custom"
});
```
```csharp C#
AnthropicClient client = new();
// Listar todas as Skills
await foreach (var skill in (await client.Skills.List()).Paginate())
{
Console.WriteLine($"{skill.ID}: {skill.DisplayName} (source: {skill.Source.Type})");
}
// Listar apenas Skills personalizadas
var customSkills = await client.Skills.List(new SkillListParams { Source = "custom" });
```
```go Go
client := anthropic.NewClient()
// Listar todas as Skills
skills := client.Skills.ListAutoPaging(context.TODO(), anthropic.SkillListParams{})
for skills.Next() {
skill := skills.Current()
fmt.Printf("%s: %s (source: %s)\n", skill.ID, skill.DisplayName, skill.Source.Type)
}
if skills.Err() != nil {
log.Fatal(skills.Err())
}
// Listar apenas Skills personalizadas
customSkills := client.Skills.ListAutoPaging(context.TODO(), anthropic.SkillListParams{
Source: anthropic.String("custom"),
})
for customSkills.Next() {
skill := customSkills.Current()
fmt.Printf("%s: %s (source: %s)\n", skill.ID, skill.DisplayName, skill.Source.Type)
}
if customSkills.Err() != nil {
log.Fatal(customSkills.Err())
}
```
```java Java
import com.anthropic.models.skills.SkillListParams;
import com.anthropic.models.skills.SkillListPage;
import com.anthropic.models.skills.Skill;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Listar Skills (primeira página)
SkillListPage skills = client.skills().list();
for (Skill skill : skills.data()) {
System.out.println(skill.id() + ": " + skill.displayName() + " (source: " + skill.source().type() + ")");
}
// Listar apenas Skills personalizadas
SkillListParams customParams = SkillListParams.builder()
.source("custom")
.build();
SkillListPage customSkills = client.skills().list(customParams);
}
```
```php PHP
$client = new Client();
// Listar Skills (primeira página)
foreach ($client->skills->list()->getItems() as $skill) {
echo "{$skill->id}: {$skill->displayName} (source: {$skill->source->type})\n";
}
// Listar apenas Skills personalizadas
$customSkills = $client->skills->list(
source: 'custom',
);
```
```ruby Ruby
client = Anthropic::Client.new
# Listar todas as Skills
client.skills.list.auto_paging_each do |skill|
puts "#{skill.id}: #{skill.display_name} (source: #{skill.source.type})"
end
# Listar apenas Skills personalizadas
custom_skills = client.skills.list(
source: "custom"
)
```
Consulte a [referência da API List Skills](https://platform.claude.com/docs/pt-BR/api/skills/list) para opções de paginação e filtragem.
### Recuperando uma Skill
Obtenha detalhes sobre uma Skill específica:
```bash cURL
curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
ant skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv
```
```python Python
client = anthropic.Anthropic()
skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")
```
```typescript TypeScript
const client = new Anthropic();
const skill = await client.skills.retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
console.log(`Skill: ${skill.display_name}`);
console.log(`Latest version: ${skill.latest_version_id}`);
console.log(`Created: ${skill.created_at}`);
```
```csharp C#
AnthropicClient client = new();
var skill = await client.Skills.Retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
Console.WriteLine($"Skill: {skill.DisplayName}");
Console.WriteLine($"Latest version: {skill.LatestVersionID}");
Console.WriteLine($"Created: {skill.CreatedAt}");
```
```go Go
client := anthropic.NewClient()
skill, err := client.Skills.Get(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.SkillGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Skill: %s\n", skill.DisplayName)
fmt.Printf("Latest version: %s\n", skill.LatestVersionID)
fmt.Printf("Created: %s\n", skill.CreatedAt)
```
```java Java
import com.anthropic.models.skills.Skill;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Skill skill = client.skills().retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
System.out.println("Skill: " + skill.displayName());
System.out.println("Latest version: " + skill.latestVersionId());
System.out.println("Created: " + skill.createdAt());
}
```
```php PHP
$client = new Client();
$skill = $client->skills->retrieve('skill_01AbCdEfGhIjKlMnOpQrStUv');
echo "Skill: {$skill->displayName}\n";
echo "Latest version: {$skill->latestVersionID}\n";
echo "Created: {$skill->createdAt->format(DATE_ATOM)}\n";
```
```ruby Ruby
client = Anthropic::Client.new
skill = client.skills.retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv")
puts "Skill: #{skill.display_name}"
puts "Latest version: #{skill.latest_version_id}"
puts "Created: #{skill.created_at}"
```
### Excluindo uma Skill
Excluir uma Skill também remove todas as suas versões.
```bash cURL
curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
```bash CLI
ant skills delete --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null
```
```python Python
client = anthropic.Anthropic()
client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
```
```typescript TypeScript
const client = new Anthropic();
await client.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
```
```csharp C#
AnthropicClient client = new();
await client.Skills.Delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
```
```go Go
client := anthropic.NewClient()
_, err := client.Skills.Delete(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.SkillDeleteParams{},
)
if err != nil {
log.Fatal(err)
}
```
```java Java
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
client.skills().delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
}
```
```php PHP
$client = new Client();
$client->skills->delete('skill_01AbCdEfGhIjKlMnOpQrStUv');
```
```ruby Ruby
client = Anthropic::Client.new
client.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv")
```
### Versionamento
As Skills suportam versionamento para gerenciar atualizações com segurança:
**Skills da Anthropic:**
* As versões usam formato de data: `20251013`
* Novas versões são lançadas conforme atualizações são feitas
* Especifique versões exatas para estabilidade
**Skills personalizadas:**
* IDs de versão gerados automaticamente: `skver_01AbCdEfGhIjKlMnOpQrStUv`
* Use `"latest"` para sempre obter a versão mais recente
* Crie novas versões ao atualizar os arquivos da Skill
Uma nova versão é um snapshot completo, não um delta: envie o conjunto completo de arquivos da Skill a cada vez. Os arquivos que você omitir não são transferidos, e o `name` no `SKILL.md` da nova versão deve corresponder ao nome existente da Skill. Os exemplos a seguir reenviam o pacote completo `financial_skill/` de [Criando uma Skill](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide#creating-a-skill).
```bash cURL
# Criar uma nova versão
NEW_VERSION=$(curl -X POST "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
-F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py")
VERSION_ID=$(echo "$NEW_VERSION" | jq -r '.id')
# Usar uma versão específica
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-5-5\",
\"max_tokens\": 4096,
\"container\": {
\"skills\": [{
\"type\": \"custom\",
\"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
\"version\": \"$VERSION_ID\"
}]
},
\"messages\": [{\"role\": \"user\", \"content\": \"Use updated Skill\"}],
\"tools\": [{\"type\": \"code_execution_20250825\", \"name\": \"code_execution\"}]
}"
# Usar a versão mais recente
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}]
},
"messages": [{"role": "user", "content": "Use latest Skill version"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Criar uma nova versão
VERSION_ID=$(ant skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file financial_skill.zip \
--transform id \
--raw-output)
# Usar uma versão específica
ant messages create <builder()
.value(Files.newInputStream(Path.of("financial_skill.zip")))
.filename("financial_skill.zip")
.contentType("application/zip")
.build())
.build();
SkillVersion newVersion = client.skills().versions()
.create("skill_01AbCdEfGhIjKlMnOpQrStUv", versionParams);
// Usa uma versão específica
MessageCreateParams specificVersionParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version(newVersion.id())
.build())
.build())
.addUserMessage("Use updated Skill")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(specificVersionParams);
System.out.println(response);
// Usa a versão mais recente
MessageCreateParams latestVersionParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.addUserMessage("Use latest Skill version")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message latestResponse = client.messages().create(latestVersionParams);
System.out.println(latestResponse);
```
```php PHP
use Anthropic\Core\FileParam;
// ...
$client = new Client();
// Criar uma nova versão
$newVersion = $client->skills->versions->create(
skillID: 'skill_01AbCdEfGhIjKlMnOpQrStUv',
files: [
FileParam::fromResource(
fopen('financial_skill/SKILL.md', 'r'),
filename: 'financial_skill/SKILL.md',
contentType: 'text/markdown',
),
FileParam::fromResource(
fopen('financial_skill/analyze.py', 'r'),
filename: 'financial_skill/analyze.py',
contentType: 'text/x-python',
),
],
);
// Usar uma versão específica
$response = $client->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Use updated Skill']],
model: 'claude-opus-5-5',
container: [
'skills' => [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => $newVersion->id
]]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
echo $response;
// Usar a versão mais recente
$latestResponse = $client->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Use latest Skill version']],
model: 'claude-opus-5-5',
container: [
'skills' => [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
echo $latestResponse;
```
```ruby Ruby
client = Anthropic::Client.new
# Criar uma nova versão
new_version = client.skills.versions.create(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
files: [
Anthropic::FilePart.new(
Pathname("financial_skill/SKILL.md"),
filename: "financial_skill/SKILL.md",
content_type: "text/markdown"
),
Anthropic::FilePart.new(
Pathname("financial_skill/analyze.py"),
filename: "financial_skill/analyze.py",
content_type: "text/x-python"
)
]
)
# Usar uma versão específica
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: new_version.id
}]
},
messages: [{ role: "user", content: "Use updated Skill" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response
# Usar a versão mais recente
latest_response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}]
},
messages: [{ role: "user", content: "Use latest Skill version" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts latest_response
```
Consulte a [referência da API Create Skill Version](https://platform.claude.com/docs/pt-BR/api/skills/versions/create) para detalhes completos.
***
## Como as Skills são carregadas
Quando você especifica Skills em um container:
1. **Descoberta de metadados:** O Claude vê os metadados de cada Skill (nome, descrição) no prompt do sistema.
2. **Carregamento de arquivos:** Os arquivos da Skill são copiados para o container em `/skills/{skill-name}/`. O diretório é o nome da Skill (`pptx` para uma Skill da Anthropic, o `name` do `SKILL.md` para uma Skill personalizada), não seu ID `skill_01...`.
3. **Uso automático:** O Claude carrega e usa automaticamente as Skills quando relevantes para sua requisição.
4. **Composição:** Múltiplas Skills se compõem para fluxos de trabalho complexos.
O Claude carrega as instruções completas da Skill apenas quando necessário.
***
## Casos de uso
As Skills se adequam tanto ao trabalho organizacional quanto ao pessoal. As organizações as usam para aplicar formatação de marca a documentos, estruturar notas e relatórios em torno de modelos da empresa e executar procedimentos analíticos específicos da empresa. Indivíduos as usam para modelos de documentos personalizados, pipelines de dados especializados e convenções de geração de código ou implantação.
### Exemplo: modelagem financeira
Combine as Skills de Excel e de análise DCF personalizada. Primeiro, crie a Skill personalizada de análise DCF:
```bash cURL
curl -X POST "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "files[]=@dcf_skill/SKILL.md;filename=dcf_skill/SKILL.md"
```
```bash CLI
ant apply dcf_skill
```
```python Python
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
dcf_skill = client.skills.create(
files=files_from_dir("/path/to/dcf_skill"),
)
print(dcf_skill.id)
```
```typescript TypeScript
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "node:fs";
const client = new Anthropic();
const dcfSkill = await client.skills.create({
files: [await toFile(fs.createReadStream("dcf_skill.zip"), "dcf_skill.zip")]
});
console.log(dcfSkill.id);
```
```csharp C#
using Anthropic.Core;
// ...
AnthropicClient client = new();
var dcfSkill = await client.Skills.Create(new SkillCreateParams
{
Files =
[
new BinaryContent
{
Stream = File.OpenRead("dcf_skill/SKILL.md"),
FileName = "dcf_skill/SKILL.md",
},
],
});
Console.WriteLine(dcfSkill.ID);
```
```go Go
client := anthropic.NewClient()
skillMd, err := os.Open("dcf_skill/SKILL.md")
if err != nil {
log.Fatal(err)
}
defer skillMd.Close()
dcfSkill, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
Files: []io.Reader{
anthropic.File(skillMd, "dcf_skill/SKILL.md", "text/markdown"),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(dcfSkill.ID)
```
```java Java
import com.anthropic.core.MultipartField;
import com.anthropic.models.skills.SkillCreateParams;
import com.anthropic.models.skills.Skill;
// ...
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
SkillCreateParams params = SkillCreateParams.builder()
.addFile(MultipartField.builder()
.value(Files.newInputStream(Path.of("dcf_skill/SKILL.md")))
.filename("dcf_skill/SKILL.md")
.contentType("text/markdown")
.build())
.build();
Skill dcfSkill = client.skills().create(params);
System.out.println(dcfSkill.id());
}
```
```php PHP
use Anthropic\Core\FileParam;
$client = new Client();
$dcfSkill = $client->skills->create(
files: [
FileParam::fromResource(
fopen('dcf_skill/SKILL.md', 'r'),
filename: 'dcf_skill/SKILL.md',
contentType: 'text/markdown',
),
],
);
echo "{$dcfSkill->id}\n";
```
```ruby Ruby
client = Anthropic::Client.new
dcf_skill = client.skills.create(
files: [
Anthropic::FilePart.new(
Pathname("dcf_skill/SKILL.md"),
filename: "dcf_skill/SKILL.md",
content_type: "text/markdown"
)
]
)
puts dcf_skill.id
```
Em seguida, use-a com a Skill de Excel para criar um modelo financeiro. Passe o ID da Skill que você criou como o `skill_id` da Skill personalizada:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Build a DCF valuation model for a SaaS company"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Build a DCF valuation model for a SaaS company
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
# Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Use com o Excel para criar um modelo financeiro
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "custom", "skill_id": dcf_skill_id, "version": "latest"},
]
},
messages=[
{
"role": "user",
"content": "Build a DCF valuation model for a SaaS company",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
// Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
const dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Use com o Excel para criar um modelo financeiro
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "custom", skill_id: dcfSkillId, version: "latest" }
]
},
messages: [
{
role: "user",
content: "Build a DCF valuation model for a SaaS company"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
// Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
var dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Use com o Excel para criar um modelo financeiro
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = dcfSkillId,
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Build a DCF valuation model for a SaaS company" }],
Tools = [new CodeExecutionTool20250825()],
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
// Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
dcfSkillID := "skill_01AbCdEfGhIjKlMnOpQrStUv"
// Use com o Excel para criar um modelo financeiro
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: dcfSkillID,
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Build a DCF valuation model for a SaaS company")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
String dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv";
// Use com a Skill do Excel para criar um modelo financeiro
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId(dcfSkillId)
.version("latest")
.build()
))
.build())
.addUserMessage("Build a DCF valuation model for a SaaS company")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
```
```php PHP
$client = new Client();
// Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
$dcfSkillId = 'skill_01AbCdEfGhIjKlMnOpQrStUv';
// Use com o Excel para criar um modelo financeiro
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Build a DCF valuation model for a SaaS company']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest'],
['type' => 'custom', 'skillID' => $dcfSkillId, 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
# Skill personalizada de análise DCF (ID obtido da resposta de criação da Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Use com o Excel para criar um modelo financeiro
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "custom", skill_id: dcf_skill_id, version: "latest" }
]
},
messages: [
{ role: "user", content: "Build a DCF valuation model for a SaaS company" }
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response
```
***
## Limites e restrições
### Limites de requisição
* **Máximo de Skills por requisição:** 20
* **Tamanho máximo de upload de Skill:** 30 MB (todos os arquivos combinados, descompactados)
* **Requisitos do frontmatter YAML:**
* `name`: Máximo de 64 caracteres, apenas letras minúsculas/números/hífens, sem tags XML, sem palavras reservadas ("anthropic", "claude")
* `description`: Máximo de 1024 caracteres, não vazio, sem tags XML
### Restrições de ambiente
As Skills são executadas no container de execução de código com estas limitações:
* **Sem acesso à rede:** Não é possível fazer chamadas a APIs externas
* **Sem instalação de pacotes em tempo de execução:** Apenas pacotes pré-instalados estão disponíveis
* **Ambiente isolado:** Um novo container é criado, a menos que você especifique um ID de container existente
Consulte [Ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) para os pacotes disponíveis.
***
## Melhores práticas
### Quando usar múltiplas Skills
Combine Skills quando as tarefas envolverem múltiplos tipos de documentos ou domínios:
**Bons casos de uso:**
* Análise de dados (Excel) + criação de apresentação (PowerPoint)
* Geração de relatório (Word) + exportação para PDF
* Lógica de domínio personalizada + geração de documentos
**Evite:**
* Incluir Skills não utilizadas (impacta o desempenho)
### Estratégia de gerenciamento de versões
As abas de SDK nesta seção mostram o valor de `container` a incluir em uma requisição Messages. As abas cURL e CLI mostram a requisição completa.
**Para produção:** fixe uma versão específica, para que atualizações de Skill nunca alterem seu comportamento implantado. Se você omitir `version` ou defini-lo como `"latest"`, as requisições usam a versão mais nova da Skill, portanto uma versão enviada por qualquer pessoa no [workspace](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide#workspace-scoped-access) altera imediatamente o que seus agentes de produção executam. O ID de versão vem da resposta de criação de versão em [Versionamento](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide#versioning) ou da [API List Skill Versions](https://platform.claude.com/docs/pt-BR/api/skills/versions/list). O ID é sempre uma string, portanto coloque-o entre aspas em JSON ou YAML mesmo quando parecer numérico.
```bash cURL
# Fixe versões específicas para garantir estabilidade
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "skver_01AbCdEfGhIjKlMnOpQrStUv"
}]
},
"messages": [{"role": "user", "content": "Analyze the sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Fixe versões específicas para garantir estabilidade
ant messages create < [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'skver_01AbCdEfGhIjKlMnOpQrStUv'
]]
];
```
```ruby Ruby
# Fixe versões específicas para garantir estabilidade
container = {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "skver_01AbCdEfGhIjKlMnOpQrStUv"
}]
}
```
**Para desenvolvimento:** use `latest` para obter automaticamente a versão mais nova enquanto você itera.
```bash cURL
# Use latest para desenvolvimento ativo
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}]
},
"messages": [{"role": "user", "content": "Analyze the sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# Use latest para desenvolvimento ativo
ant messages create < [[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]]
];
```
```ruby Ruby
# Use latest para desenvolvimento ativo
container = {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}]
}
```
### Considerações sobre cache de prompt
Se você usa [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) ("prompt caching"), alterar a lista de Skills em seu container quebra o cache. As Skills são renderizadas no prompt do sistema em uma ordem fixa, portanto a mesma lista produz o mesmo prefixo armazenável em cache:
```bash cURL
# As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
"messages": [{"role": "user", "content": "Analyze sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
# Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"}
]
},
"messages": [{"role": "user", "content": "Create a presentation"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# As Skills são renderizadas no prompt do sistema em uma ordem fixa e amigável ao cache
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Analyze sales data
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
client = anthropic.Anthropic()
# As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
response1 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[{"role": "user", "content": "Analyze sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
response2 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest",
}, # prefix change: cache miss
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const client = new Anthropic();
// As Skills são renderizadas no prompt do sistema em uma ordem fixa e amigável ao cache
const response1 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica resulta em cache hit
const response2 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "anthropic", skill_id: "pptx", version: "latest" } // prefix change: cache miss
]
},
messages: [{ role: "user", content: "Create a presentation" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C#
AnthropicClient client = new();
// As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Analyze sales data" }],
Tools = [new CodeExecutionTool20250825()],
};
var response1 = await client.Messages.Create(parameters1);
Console.WriteLine(response1);
// Conjunto de Skills diferente ([xlsx] vs [xlsx, pptx]) = prefixo diferente: cache miss (um conjunto idêntico é um cache hit)
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "xlsx",
Version = "latest",
},
new SkillParams
{
Type = SkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Create a presentation" }],
Tools = [new CodeExecutionTool20250825()],
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine(response2);
```
```go Go
client := anthropic.NewClient()
// As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze sales data")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response1)
// Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.SkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Create a presentation")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response2)
```
```java Java
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// As Skills são renderizadas no prompt do sistema em uma ordem fixa e amigável ao cache
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build()
))
.build())
.addUserMessage("Analyze sales data")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response1 = client.messages().create(params1);
System.out.println(response1);
// Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.skills(List.of(
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
SkillParams.builder()
.type(SkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build()
))
.build())
.addUserMessage("Create a presentation")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response2 = client.messages().create(params2);
System.out.println(response2);
}
```
```php PHP
$client = new Client();
// As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
$response1 = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze sales data']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response1;
// Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
$response2 = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
['type' => 'anthropic', 'skillID' => 'xlsx', 'version' => 'latest'],
['type' => 'anthropic', 'skillID' => 'pptx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response2;
```
```ruby Ruby
client = Anthropic::Client.new
# As Skills são renderizadas no prompt do sistema em uma ordem fixa e amigável ao cache
response1 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response1
# Alterar a lista de Skills ([xlsx] vs [xlsx, pptx]) altera o prefixo: cache miss; uma lista idêntica gera cache hit
response2 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "anthropic", skill_id: "pptx", version: "latest" } # prefix change: cache miss
]
},
messages: [{ role: "user", content: "Create a presentation" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response2
```
Para o melhor desempenho de cache, mantenha sua lista de Skills, incluindo sua ordem, consistente entre as requisições. Fixar versões de Skills personalizadas também ajuda: com `"latest"`, publicar uma nova versão pode invalidar o prefixo em cache se ela alterar a descrição da Skill.
### Tratamento de erros
Trate erros relacionados a Skills de forma adequada:
Este fluxo de tratamento de erros exige mais lógica do que um único comando de shell, então use o Claude SDK para isso. Uma requisição que falha por causa de um problema com uma Skill retorna HTTP 400. O campo `error.message` no corpo da resposta JSON descreve o problema.
```bash CLI
if ! RESULT=$(ant messages create \
--transform-error error.message \
--format-error yaml 2>&1 <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Process data
tools:
- type: code_execution_20250825
name: code_execution
YAML
); then
case "$RESULT" in
*skill*)
printf 'Skill error: %s\n' "$RESULT"
# Trata erros específicos de skills
;;
*)
printf '%s\n' "$RESULT" >&2
exit 1
;;
esac
fi
```
```python Python
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Process data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
except anthropic.BadRequestError as e:
if "skill" in str(e):
print(f"Skill error: {e}")
# Trata erros específicos de skills
else:
raise
```
```typescript TypeScript
const client = new Anthropic();
try {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{ type: "custom", skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv", version: "latest" }
]
},
messages: [{ role: "user", content: "Process data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
console.log(response);
} catch (error) {
if (error instanceof Anthropic.BadRequestError && error.message.includes("skill")) {
console.error(`Skill error: ${error.message}`);
// Trata erros específicos de skills
} else {
throw error;
}
}
```
```csharp C#
using Anthropic.Exceptions;
// ...
AnthropicClient client = new();
try
{
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = new ContainerParams
{
Skills =
[
new SkillParams
{
Type = SkillParamsType.Custom,
SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest",
},
],
},
Messages = [new() { Role = Role.User, Content = "Process data" }],
Tools = [new CodeExecutionTool20250825()],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
}
catch (AnthropicBadRequestException e) when (e.Message.Contains("skill"))
{
Console.WriteLine($"Skill error: {e.Message}");
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfContainers: &anthropic.ContainerParams{
Skills: []anthropic.SkillParams{
{
Type: anthropic.SkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Process data")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
},
})
if err != nil {
var apierr *anthropic.Error
if errors.As(err, &apierr) && apierr.Type() == anthropic.ErrorTypeInvalidRequestError &&
strings.Contains(apierr.Error(), "skill") {
fmt.Printf("Skill error: %v\n", apierr)
} else {
log.Fatal(err)
}
return
}
fmt.Println(response)
```
```java Java
import com.anthropic.errors.BadRequestException;
import com.anthropic.models.messages.ContainerParams;
import com.anthropic.models.messages.SkillParams;
import com.anthropic.models.messages.CodeExecutionTool20250825;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
try {
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container(ContainerParams.builder()
.addSkill(SkillParams.builder()
.type(SkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.addUserMessage("Process data")
.addTool(CodeExecutionTool20250825.builder().build())
.build();
Message response = client.messages().create(params);
System.out.println(response);
} catch (BadRequestException e) {
if (e.getMessage().contains("skill")) {
System.err.println("Skill error: " + e.getMessage());
} else {
throw e;
}
}
}
```
```php PHP
use Anthropic\Core\Exceptions\BadRequestException;
$client = new Client();
try {
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Process data']
],
model: 'claude-opus-5-5',
container: [
'skills' => [
[
'type' => 'custom',
'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
} catch (BadRequestException $e) {
if (str_contains($e->getMessage(), 'skill')) {
echo "Skill error: " . $e->getMessage();
} else {
throw $e;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
begin
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [{ role: "user", content: "Process data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
rescue Anthropic::Errors::BadRequestError => e
if e.message.include?("skill")
puts "Skill error: #{e.message}"
else
raise
end
end
```
***
## Migrar de `skills-2025-10-02`
A Skills API saiu da fase beta e não precisa de cabeçalho beta. Migrar de `skills-2025-10-02` é opcional: as requisições que ainda o enviam continuam funcionando e continuam retornando os formatos de resposta beta, portanto uma integração existente continua funcionando até que você a altere. Remover o cabeçalho muda essas requisições para os formatos documentados nesta página:
| | Com `skills-2025-10-02` | Sem o cabeçalho |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rótulo da Skill | `display_title` (até 64 caracteres, único por workspace) | `display_name` (até 255 caracteres, não único); derivado do `name` do `SKILL.md` quando omitido |
| Ponteiro para a versão mais nova | `latest_version`, uma string de microssegundos epoch como `"1759178010641129"` | `latest_version_id`, um ID de versão como `"skver_01AbCdEfGhIjKlMnOpQrStUv"`; `GET /v1/skills/{skill_id}/versions/latest` o resolve em uma única chamada |
| Identificador de versão em URLs | String de microssegundos epoch | ID de versão (`skver_...`). IDs capturados durante a beta com o prefixo `skill_version_` são aceitos como entrada. |
| Objeto de versão | Inclui `directory` (sempre igual ao `name` da Skill) | Sem campo `directory` |
| `source` | Uma string, `"custom"` ou `"anthropic"` | Um objeto, por exemplo `{"type": "custom"}`; o valor do catálogo de exemplos é `"anthropic_example"` |
| Respostas de listagem | `{ data, has_more, next_page }` | `{ data, next_page }`; `limit` de 1 a 1.000 (padrão 20) |
| Ordem da lista de versões | Mais antiga primeiro | Mais nova primeiro, `limit` padrão 20. Cursores de página de um formato não são válidos no outro. |
| Excluir uma Skill | Retorna um erro 400 enquanto existir qualquer versão | Exclui a Skill e todas as suas versões |
| Excluir a única versão de uma Skill | Permitido, deixando uma Skill sem versões | Retorna um erro 400; envie uma versão substituta primeiro ou exclua a Skill |
| Layout de upload | Os arquivos devem ficar dentro de um diretório de nível superior cujo nome corresponda ao `name` da Skill | O `SKILL.md` pode ficar na raiz do upload; os caminhos armazenados são os mesmos de qualquer forma |
| Tipos de resposta | `CreateSkillResponse`, `GetSkillResponse` e um tipo por operação | `Skill`, `SkillVersion`, `DeletedSkill`, `DeletedSkillVersion` |
Para migrar:
1. **Remova o cabeçalho beta.** Retire `anthropic-beta: skills-2025-10-02` de suas requisições. Nos SDKs, chame `client.skills` em vez de `client.beta.skills`; manter `client.beta.skills` funciona apenas nas [versões de SDK que não enviam mais o cabeçalho](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide#sdk-beta-namespace). Versões anteriores o enviam a partir de `client.beta.skills` mesmo sem argumento `betas`.
2. **Renomeie os campos** em seu código: `display_title` para `display_name`, `latest_version` para `latest_version_id`, e leia `source.type` em vez de comparar `source` com uma string.
3. **Use IDs de versão.** Onde quer que você tenha armazenado uma versão em microssegundos epoch, armazene o `id` da versão em vez disso, ou use `latest`. As referências de Skill em requisições Messages aceitam um ID de versão, `latest` ou (para Skills da Anthropic) a versão do catálogo.
4. **Revise as chamadas de exclusão.** `DELETE /v1/skills/{skill_id}` agora remove todas as versões junto com a Skill. Se você dependia da recusa da beta como salvaguarda, adicione sua própria verificação.
Após a migração, `client.skills.delete(skill_id)` e `client.beta.skills.delete(skill_id)` excluem a Skill junto com todas as suas versões em uma única chamada.
Uma Skill cujas versões foram todas excluídas durante a beta não tem versão atual para retornar: `GET /v1/skills/{skill_id}` retorna um erro 400 e a Skill é omitida das respostas de listagem até que você envie uma versão para ela. Você ainda pode excluí-la.
### Namespace beta do SDK
A partir do SDK Python 1.2.0, SDK TypeScript 0.122.0, SDK Go 1.68.0, SDK Java 2.59.0, SDK Ruby 1.67.0 e SDK C# 12.44.0, `client.beta.skills` não envia mais `skills-2025-10-02` e retorna os mesmos formatos que `client.skills`, com nomes de tipo prefixados com `Beta` (`BetaSkill`, `BetaSkillVersion`, `BetaDeletedSkill`, `BetaDeletedSkillVersion`). Ele aceita um argumento `betas` para recursos de Skills que ainda estão em beta. Nos tipos beta de Messages, o tipo de referência de Skill do container foi renomeado de `BetaSkill` para `BetaContainerSkill` (mesmos campos: `type`, `skill_id`, `version`); `BetaSkill` agora nomeia o recurso Skill, correspondendo a `Skill` e `ContainerSkill` nos tipos não beta. Versões anteriores do SDK são tipadas com os formatos beta; se você depende desses tipos, permaneça em uma versão anterior até migrar.
## Retenção de dados
Agent Skills não são cobertas por acordos de ZDR. As definições de Skill e os dados de execução são retidos de acordo com a política padrão de retenção de dados da Anthropic.
Para elegibilidade de ZDR em todos os recursos, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
## Registro de auditoria
Se sua organização tem a [Compliance API](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-api) habilitada, seu [Activity Feed](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-activity-feed) registra a criação e a exclusão de Skills e versões de Skill feitas com uma chave de API do Claude ou a partir do Claude Console. Operações que ocorrem enquanto a Compliance API está desativada não são registradas e não podem ser recuperadas posteriormente, portanto [configure a Compliance API](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-api-access) antes de depender dessa trilha de auditoria.
## Próximos passos
Referência completa da API com todos os endpoints
Aprenda a escrever Skills eficazes que o Claude consiga descobrir e usar com sucesso.
Execute código Python e bash em um container isolado para analisar dados, gerar arquivos e iterar em soluções.