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

As Skills se integram à 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

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, 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`	ID de versão: `skver_01AbCdEfGhIjKlMnOpQrStUv` ou `latest`
Gerenciamento	Pré-construídas e mantidas pela Anthropic	Envie e gerencie através da Skills API
Disponibilidade	Disponíveis para todos os usuários	Privadas ao 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
Ferramenta de execução de código habilitada em suas requisições

As Skills estão disponíveis de forma geral na API do Claude e não exigem um cabeçalho anthropic-beta, seja para a Skills API ou para container.skills em requisições Messages. Os exemplos neste guia ainda enviam o cabeçalho beta skills-2025-10-02 (além de code-execution-2025-08-25 em requisições Messages) e usam o namespace beta dos SDKs. Ambos os cabeçalhos continuam sendo opt-ins válidos, então os exemplos funcionam como escritos, e você pode omiti-los em suas próprias requisições.

As 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

As Skills são especificadas usando o parâmetro container na Messages API. Você pode incluir até 20 Skills por 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 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:

As 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 o 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"},
    {
        # Passe 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

As Skills podem executar operações que exigem vários 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 várias Skills

Combine várias 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

As Skills personalizadas são acessíveis a todo o seu workspace, não limitadas a um usuário final, conversa ou sessão. Qualquer chave de API no mesmo workspace pode ler, invocar e excluir todas as Skills personalizadas enviadas para lá, e todas as suas chaves compartilham o Default Workspace da sua organização, a menos que você as tenha atribuído a workspaces separados.

Se você está construindo uma plataforma multi-tenant na Skills API, crie um workspace separado para cada tenant. O workspace é o limite de isolamento para Skills personalizadas, então um workspace por tenant dá às Skills de cada tenant isolamento rígido de todos os outros tenants. Cada organização pode ter até 100 workspaces por padrão (consulte Como os workspaces funcionam); 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 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 (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.

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

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.

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:

# 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

Excluir uma Skill também remove todas as suas versões. A exclusão em cascata é um comportamento exclusivo da GA, então, diferentemente dos outros exemplos neste guia, estes chamam a superfície GA diretamente em vez do namespace beta.

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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

# 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: o Claude vê os metadados de cada Skill (nome, descrição) no prompt do sistema.
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....
Uso automático: o Claude carrega e usa Skills automaticamente quando relevantes para sua requisição.
Composição: várias 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. Organizações as usam para aplicar formatação de marca a documentos, estruturar anotações 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: 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 de API 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 para os pacotes disponíveis.

Melhores práticas

Quando usar várias Skills

Combine Skills quando as tarefas envolverem vários tipos de documentos ou domínios:

Bons casos de uso:

Análise de dados (Excel) + criação de apresentações (PowerPoint)
Geração de relatórios (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 ser incluído 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 recente da Skill, então uma versão enviada por qualquer pessoa no workspace 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 ou da API List Skill Versions. O ID é sempre uma string: coloque IDs de timestamp epoch 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 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, alterar a lista de Skills em seu container invalida o cache. As 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 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:

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 de skill
    else:
        raise

Retenção de dados

Agent Skills não são cobertas por acordos ZDR. Definições de Skills 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 ZDR em todos os recursos, consulte API e retenção de dados.

Registro de auditoria

Se sua organização tem a Compliance API habilitada, seu Activity Feed registra a criação e exclusão de Skills e versões de Skills 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, então configure a Compliance API antes de depender dessa trilha de auditoria.

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?

MessagesSkills

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`	ID de versão: `skver_01AbCdEfGhIjKlMnOpQrStUv` ou `latest`
Gerenciamento	Pré-construídas e mantidas pela Anthropic	Envie e gerencie através da Skills API
Disponibilidade	Disponíveis para todos os usuários	Privadas ao seu workspace

Pré-requisitos

Para usar Skills, você precisa de:

Chave de API do Claude do Claude Console
Ferramenta de execução de código habilitada em suas requisições

As 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

As Skills são especificadas usando o parâmetro container na Messages API. Você pode incluir até 20 Skills por 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 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:

As 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"},
    {
        # Passe 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

As Skills podem executar operações que exigem vários 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 várias Skills

Combine várias 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

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

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.

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

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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 arquivos da 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: o Claude vê os metadados de cada Skill (nome, descrição) no prompt do sistema.
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....
Uso automático: o Claude carrega e usa Skills automaticamente quando relevantes para sua requisição.
Composição: várias 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

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: 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 de API 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 para os pacotes disponíveis.

Melhores práticas

Quando usar várias Skills

Combine Skills quando as tarefas envolverem vários tipos de documentos ou domínios:

Bons casos de uso:

Análise de dados (Excel) + criação de apresentações (PowerPoint)
Geração de relatórios (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 ser incluído em uma requisição 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 latest 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 de skill
    else:
        raise

Retenção de dados

Agent Skills não são cobertas por acordos ZDR. Definições de Skills 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 ZDR em todos os recursos, consulte API e retenção de dados.

Registro de auditoria

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 várias 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 várias Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Registro de auditoria

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 várias 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 várias Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Registro de auditoria

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 várias 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 várias Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Registro de auditoria

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 várias 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 várias Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Registro de auditoria

Próximos passos