Usando Agent Skills com a 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.

Links rápidos

Visão geral

As Skills se integram à Messages API por meio da ferramenta de execução de código ("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:

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:

1. Chave de API do Claude obtida no Claude Console
2. Ferramenta de execução de código 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.

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:

client = anthropic.Anthropic()

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

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).
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 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: Usar uma Skill para criar um arquivo
response = client.messages.create(
    model="claude-opus-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: Extrair 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: Baixar 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)

    # Etapa 4: Salvar em 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.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)

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 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.messages.create(
    model="claude-opus-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"}],
)

# Continua a conversa com o mesmo contêiner
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Leva 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 realizar operações que exigem múltiplos turnos. Trate os motivos de parada pause_turn:

client = anthropic.Anthropic()

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

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Trata 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.messages.create(
        model="claude-opus-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"}],
    )

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.messages.create(
    model="claude-opus-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"}],
)

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 name e description, além de quaisquer scripts ou recursos de apoio. Consulte Comece a usar Agent Skills na API para criar uma, e a lista de Requisitos após os exemplos para as restrições completas.

Envie sua Skill personalizada para torná-la disponível 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 skills create --file financial_skill.zip

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

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 skills list

# Listar apenas Skills personalizadas
ant 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 skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Excluindo uma Skill

Excluir uma Skill também remove todas as suas versões.

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

# 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 <<YAML
model: claude-opus-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
YAML

# Usar a versão mais recente
ant messages create <<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:

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 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.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Usar com Excel para criar modelo financeiro
response = client.messages.create(
    model="claude-opus-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)

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 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 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, portanto coloque-o entre aspas em JSON ou YAML mesmo quando parecer numérico.

# Fixe em versões específicas para 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.

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

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",
    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: uma falha de cache, enquanto uma lista idêntica é um acerto de cache
response2 = client.messages.create(
    model="claude-opus-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"}],
)

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:

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-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}")
        # Tratar erros específicos de skills
    else:
        raise

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:

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

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.

Registro de auditoria

Se sua organização tem a Compliance API habilitada, seu 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 antes de depender dessa trilha de auditoria.

Próximos passos