Usando Agent Skills com a API

Aprenda a usar Agent Skills para estender as capacidades do Claude através da API.

Agent Skills estendem as capacidades do Claude através de pastas organizadas de instruções, scripts e recursos. Este guia mostra como usar Skills pré-construídas e personalizadas com a API do Claude.

Links rápidos

Comece a usar Agent Skills na API

Aprenda a usar Agent Skills para criar documentos com a API do Claude em menos de 10 minutos.

Melhores práticas para criação de Skills

Aprenda a escrever Skills eficazes que o Claude possa descobrir e usar com sucesso.

Visão geral

Skills se integram com a Messages API através da ferramenta de execução de código. 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 de container.

Usando Skills

Skills se integram de forma idêntica na Messages API, independentemente da origem. Você especifica Skills no parâmetro container com um skill_id, type e, opcionalmente, version, 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`	Timestamp de época: `1759178010641129` ou `latest`
Gerenciamento	Pré-construídas e mantidas pela Anthropic	Envie e gerencie através da Skills API
Disponibilidade	Disponível para todos os usuários	Privada para seu workspace

Ambas as origens de Skills são retornadas pelo endpoint List Skills (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:

Chave de API do Claude do Claude Console
Cabeçalhos beta:
- code-execution-2025-08-25 - Habilita execução de código (obrigatório para Skills)
- skills-2025-10-02 - Habilita a Skills API
- files-api-2025-04-14 - Obrigatório apenas quando você usa a Files API para enviar arquivos de entrada ou baixar arquivos que uma Skill produz
Ferramenta de execução de código habilitada em suas requisições

Skills exigem a ferramenta de execução de código, então use um modelo da sua lista de compatibilidade de modelos.

Usando Skills em Messages

Parâmetro container

Skills são especificadas usando o parâmetro container na Messages API. Você pode incluir até 8 Skills em cada requisição.

A estrutura é idêntica para Skills da Anthropic e personalizadas. Especifique os campos obrigatórios type e skill_id e, opcionalmente, inclua version para fixar uma versão específica:

client = anthropic.Anthropic()

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

Baixando arquivos gerados

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

Skills criam arquivos durante a execução de código.
A resposta inclui um file_id para cada arquivo criado, dentro de blocos de resultado da ferramenta de execução de código (consulte Formato de resposta).
Use a Files API para baixar o conteúdo real do arquivo.
Salve localmente ou processe conforme necessário.

Para fornecer arquivos de entrada para as Skills trabalharem, envie-os com a Files API e referencie-os em sua requisição com um bloco de upload de container.

Exemplo: criando e baixando um arquivo Excel

client = anthropic.Anthropic()

# Etapa 1: Use uma Skill para criar um arquivo
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "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 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 contendo um file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Etapa 3: Baixe o arquivo usando a Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Etapa 4: Salve no disco
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operações adicionais da Files API:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obter metadados do arquivo
file_info = client.beta.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.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Excluir um arquivo
client.beta.files.delete(file_id=file_id)

Conversas multi-turno

O objeto container da resposta carrega o id do container e o timestamp expires_at (consulte Reutilização de container para detalhes sobre tempo de vida). Reutilize o mesmo container em várias mensagens especificando o ID do container:

client = anthropic.Anthropic()

# A primeira requisição cria o contêiner
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Continue a conversa com o mesmo contêiner
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Transfira o texto do assistente adiante; container.id carrega o estado de execução
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Operações de longa duração

Skills podem executar operações que exigem múltiplos turnos. Trate os stop reasons pause_turn:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Lidar com pause_turn para operações longas
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

Usando múltiplas Skills

Combine múltiplas Skills em uma única requisição para lidar com fluxos de trabalho complexos:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "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"}],
)

Gerenciando Skills personalizadas

Criando uma Skill

Um pacote de Skill é um diretório contendo um arquivo SKILL.md no nível superior com frontmatter YAML de name e description, além de quaisquer scripts ou recursos de suporte. Consulte Comece a usar Agent Skills na API para criar um, e a lista de Requisitos após os exemplos para as restrições completas.

Envie sua Skill personalizada para disponibilizá-la em seu workspace. Você pode enviar um arquivo zip ou objetos de arquivo individuais. O SDK Python também fornece um helper files_from_dir que aceita um caminho de diretório.

Os arquivos são identificados pelo nome de arquivo que você anexa. Uploads por arquivo devem manter um diretório de nível superior comum em seus caminhos (o sufixo ;filename= no exemplo cURL e os argumentos de nome de arquivo nos exemplos de SDK). Um arquivo zip deve conter o diretório da skill como sua única entrada de nível superior. Para a skill do passo a passo, crie um com zip -r financial_skill.zip financial_skill/ e substitua-o pelo placeholder example_skill.zip nas opções de upload de zip.

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# O upload por arquivo requer nomes de arquivo qualificados por caminho, que a CLI
# não consegue definir atualmente. Faça upload de um arquivo zip em vez disso.

Requisitos:

Deve incluir um arquivo SKILL.md no nível superior
Todos os arquivos devem especificar um diretório raiz comum em seus caminhos
O nome do diretório de nível superior deve corresponder ao name no frontmatter do SKILL.md (insensível a maiúsculas/minúsculas e underscores: Financial_Skill corresponde a financial-skill)
display_title é opcional: quando omitido, é derivado do name do SKILL.md; um valor explícito deve ser único entre as skills personalizadas em seu 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.

Listando Skills

Recupere todas as Skills disponíveis para seu workspace, incluindo tanto Skills pré-construídas da Anthropic quanto suas Skills personalizadas. Use o parâmetro source para filtrar por tipo de skill:

# Listar todas as Skills
ant beta:skills list

# Listar apenas Skills personalizadas
ant beta:skills list --source custom

Consulte a referência da API List Skills para opções de paginação e filtragem.

Recuperando uma Skill

Obtenha detalhes sobre uma Skill específica:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Excluindo uma Skill

Para excluir uma Skill, você deve primeiro excluir todas as suas versões:

# Etapa 1: Liste as versões e, em seguida, exclua cada uma
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version \
  --raw-output

# Repita para cada id de versão retornado pela lista
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Etapa 2: Exclua a Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Tentar excluir uma Skill com versões existentes retorna um erro 400.

Versionamento

Skills suportam versionamento para gerenciar atualizações com segurança:

Skills da Anthropic:

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:

Timestamps de época gerados automaticamente: 1759178010641129
Use "latest" para sempre obter a versão mais recente
Crie novas versões ao atualizar arquivos de Skill

Uma nova versão é um snapshot completo, não um delta: envie o conjunto completo de arquivos da Skill a cada vez, sob o mesmo nome de diretório de nível superior usado na criação. Arquivos que você omitir não são mantidos. Os exemplos a seguir reenviam o pacote completo financial_skill/ de Criando uma Skill.

# Criar uma nova versão
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Usar versão específica
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Usar a versão mais recente
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

Consulte a referência da API Create Skill Version para detalhes completos.

Como as Skills são carregadas

Quando você especifica Skills em um container:

Descoberta de metadados: Claude vê metadados de cada Skill (nome, descrição) no prompt do sistema.
Carregamento de arquivos: Arquivos de 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....
Uso automático: Claude carrega e usa Skills automaticamente quando relevantes para sua requisição.
Composição: Múltiplas Skills se compõem para fluxos de trabalho complexos.

Claude carrega instruções completas de Skill apenas quando necessário.

Casos de uso

Skills se adequam tanto ao trabalho organizacional quanto pessoal. Organizações as usam para aplicar formatação de marca a documentos, estruturar notas e relatórios em torno de templates da empresa e executar procedimentos analíticos específicos da empresa. Indivíduos as usam para templates de documentos personalizados, pipelines de dados especializados e convenções de geração de código ou implantação.

Exemplo: modelagem financeira

Combine Skills de Excel e de análise DCF personalizada:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Criar Skill personalizada de análise DCF

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Usar com Excel para criar modelo financeiro
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "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)

Limites e restrições

Limites de requisição

Máximo de Skills por requisição: 8
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

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 de API externas
Sem instalação de pacotes em tempo de execução: Apenas pacotes pré-instalados 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 para 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 de 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. O ID da versão vem da resposta de create-version em Versionamento ou da API List Skill Versions. O ID é sempre uma string: coloque IDs de timestamp de época entre aspas em JSON ou YAML.

# Fixe em versões específicas para estabilidade
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

Para desenvolvimento: use latest para obter a versão mais recente automaticamente enquanto você itera.

# Use a versão mais recente 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, alterar a lista de Skills em seu container invalida o cache. Skills são renderizadas no prompt do sistema em uma ordem fixa, então a mesma lista produz o mesmo prefixo cacheável:

client = anthropic.Anthropic()

# As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "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: um cache miss, enquanto uma lista idêntica é um cache hit
response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "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"}],
)

Para melhor desempenho de cache, mantenha sua lista de Skills, incluindo sua ordem, consistente entre 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:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {
                    "type": "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 da skill
    else:
        raise

Retenção de dados

Agent Skills não são cobertas por acordos de ZDR. Definições de Skill e 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.

Próximos passos

Referência da API

Referência completa da API com todos os endpoints

Melhores práticas para criação de Skills

Aprenda a escrever Skills eficazes que o Claude possa descobrir e usar com sucesso.

Ferramenta de execução de código

Execute código Python e bash em um container isolado para analisar dados, gerar arquivos e iterar em soluções.

Was this page helpful?

MensagensSkills

Usando Agent Skills com a API

Aprenda a usar Agent Skills para estender as capacidades do Claude através da API.

Links rápidos

Comece a usar Agent Skills na API

Aprenda a usar Agent Skills para criar documentos com a API do Claude em menos de 10 minutos.

Melhores práticas para criação de Skills

Aprenda a escrever Skills eficazes que o Claude possa descobrir e usar com sucesso.

Visão geral

Usando Skills

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`	Timestamp de época: `1759178010641129` ou `latest`
Gerenciamento	Pré-construídas e mantidas pela Anthropic	Envie e gerencie através da Skills API
Disponibilidade	Disponível para todos os usuários	Privada para seu workspace

Pré-requisitos

Para usar Skills, você precisa de:

Chave de API do Claude do Claude Console
Cabeçalhos beta:
- code-execution-2025-08-25 - Habilita execução de código (obrigatório para Skills)
- skills-2025-10-02 - Habilita a Skills API
- files-api-2025-04-14 - Obrigatório apenas quando você usa a Files API para enviar arquivos de entrada ou baixar arquivos que uma Skill produz
Ferramenta de execução de código habilitada em suas requisições

Skills exigem a ferramenta de execução de código, então use um modelo da sua lista de compatibilidade de modelos.

Usando Skills em Messages

Parâmetro container

Skills são especificadas usando o parâmetro container na Messages API. Você pode incluir até 8 Skills em cada requisição.

A estrutura é idêntica para Skills da Anthropic e personalizadas. Especifique os campos obrigatórios type e skill_id e, opcionalmente, inclua version para fixar uma versão específica:

client = anthropic.Anthropic()

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

Baixando arquivos gerados

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

Skills criam arquivos durante a execução de código.
A resposta inclui um file_id para cada arquivo criado, dentro de blocos de resultado da ferramenta de execução de código (consulte Formato de resposta).
Use a Files API para baixar o conteúdo real do arquivo.
Salve localmente ou processe conforme necessário.

Para fornecer arquivos de entrada para as Skills trabalharem, envie-os com a Files API e referencie-os em sua requisição com um bloco de upload de container.

Exemplo: criando e baixando um arquivo Excel

client = anthropic.Anthropic()

# Etapa 1: Use uma Skill para criar um arquivo
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "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 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 contendo um file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Etapa 3: Baixe o arquivo usando a Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Etapa 4: Salve no disco
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operações adicionais da Files API:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obter metadados do arquivo
file_info = client.beta.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.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Excluir um arquivo
client.beta.files.delete(file_id=file_id)

Conversas multi-turno

client = anthropic.Anthropic()

# A primeira requisição cria o contêiner
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Continue a conversa com o mesmo contêiner
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Transfira o texto do assistente adiante; container.id carrega o estado de execução
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Operações de longa duração

Skills podem executar operações que exigem múltiplos turnos. Trate os stop reasons pause_turn:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Lidar com pause_turn para operações longas
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

Usando múltiplas Skills

Combine múltiplas Skills em uma única requisição para lidar com fluxos de trabalho complexos:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "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"}],
)

Gerenciando Skills personalizadas

Criando uma Skill

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# O upload por arquivo requer nomes de arquivo qualificados por caminho, que a CLI
# não consegue definir atualmente. Faça upload de um arquivo zip em vez disso.

Requisitos:

Deve incluir um arquivo SKILL.md no nível superior
Todos os arquivos devem especificar um diretório raiz comum em seus caminhos
O nome do diretório de nível superior deve corresponder ao name no frontmatter do SKILL.md (insensível a maiúsculas/minúsculas e underscores: Financial_Skill corresponde a financial-skill)
display_title é opcional: quando omitido, é derivado do name do SKILL.md; um valor explícito deve ser único entre as skills personalizadas em seu 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.

Listando Skills

# Listar todas as Skills
ant beta:skills list

# Listar apenas Skills personalizadas
ant beta:skills list --source custom

Consulte a referência da API List Skills para opções de paginação e filtragem.

Recuperando uma Skill

Obtenha detalhes sobre uma Skill específica:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Excluindo uma Skill

Para excluir uma Skill, você deve primeiro excluir todas as suas versões:

# Etapa 1: Liste as versões e, em seguida, exclua cada uma
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version \
  --raw-output

# Repita para cada id de versão retornado pela lista
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Etapa 2: Exclua a Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Tentar excluir uma Skill com versões existentes retorna um erro 400.

Versionamento

Skills suportam versionamento para gerenciar atualizações com segurança:

Skills da Anthropic:

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:

Timestamps de época gerados automaticamente: 1759178010641129
Use "latest" para sempre obter a versão mais recente
Crie novas versões ao atualizar arquivos de Skill

# Criar uma nova versão
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Usar versão específica
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Usar a versão mais recente
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

Consulte a referência da API Create Skill Version para detalhes completos.

Como as Skills são carregadas

Quando você especifica Skills em um container:

Descoberta de metadados: Claude vê metadados de cada Skill (nome, descrição) no prompt do sistema.
Carregamento de arquivos: Arquivos de 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....
Uso automático: Claude carrega e usa Skills automaticamente quando relevantes para sua requisição.
Composição: Múltiplas Skills se compõem para fluxos de trabalho complexos.

Claude carrega instruções completas de Skill apenas quando necessário.

Casos de uso

Exemplo: modelagem financeira

Combine Skills de Excel e de análise DCF personalizada:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Criar Skill personalizada de análise DCF

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Usar com Excel para criar modelo financeiro
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "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)

Limites e restrições

Limites de requisição

Máximo de Skills por requisição: 8
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

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 de API externas
Sem instalação de pacotes em tempo de execução: Apenas pacotes pré-instalados 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 para 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 de Messages. As abas cURL e CLI mostram a requisição completa.

# Fixe em versões específicas para estabilidade
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

Para desenvolvimento: use latest para obter a versão mais recente automaticamente enquanto você itera.

# Use a versão mais recente para desenvolvimento ativo
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

Considerações sobre cache de prompt

client = anthropic.Anthropic()

# As Skills são renderizadas no prompt do sistema em uma ordem fixa e favorável ao cache
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "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: um cache miss, enquanto uma lista idêntica é um cache hit
response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "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"}],
)

Tratamento de erros

Trate erros relacionados a Skills de forma adequada:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {
                    "type": "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 da skill
    else:
        raise

Retenção de dados

Agent Skills não são cobertas por acordos de ZDR. Definições de Skill e 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.

Próximos passos

Referência da API

Referência completa da API com todos os endpoints

Melhores práticas para criação de Skills

Aprenda a escrever Skills eficazes que o Claude possa descobrir e usar com sucesso.

Ferramenta de execução de código

Execute código Python e bash em um container isolado para analisar dados, gerar arquivos e iterar em soluções.

Was this page helpful?

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

Parâmetro container

Baixando arquivos gerados

Conversas multi-turno

Operações de longa duração

Usando múltiplas Skills

Gerenciando Skills personalizadas

Criando uma Skill

Listando Skills

Recuperando uma Skill

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

Parâmetro container

Baixando arquivos gerados

Conversas multi-turno

Operações de longa duração

Usando múltiplas Skills

Gerenciando Skills personalizadas

Criando uma Skill

Listando Skills

Recuperando uma Skill

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

Parâmetro container

Baixando arquivos gerados

Conversas multi-turno

Operações de longa duração

Usando múltiplas Skills

Gerenciando Skills personalizadas

Criando uma Skill

Listando Skills

Recuperando uma Skill

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

Parâmetro container

Baixando arquivos gerados

Conversas multi-turno

Operações de longa duração

Usando múltiplas Skills

Gerenciando Skills personalizadas

Criando uma Skill

Listando Skills

Recuperando uma Skill

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos