Usando Agent Skills com a API

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

Para referência completa da API, incluindo esquemas de solicitação/resposta e todos os parâmetros, consulte:

Referência da API de Gerenciamento de Skills - Operações CRUD para Skills
Referência da API de Versões de Skills - Gerenciamento de versões

Links Rápidos

Comece com Agent Skills

Crie sua primeira Skill

Crie Skills Personalizadas

Melhores práticas para criar Skills

Visão Geral

Para uma análise profunda da arquitetura e aplicações do mundo real de Agent Skills, leia nosso blog de engenharia: Equipando agentes para o mundo real com Agent Skills.

Skills se integram com a API de Mensagens 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, a forma de integração é idêntica—ambas requerem execução de código e usam a mesma estrutura container.

Usando Skills

Skills se integram de forma idêntica na API de Mensagens independentemente da fonte. Você especifica Skills no parâmetro container com um skill_id, type e version opcional, e elas são executadas no ambiente de execução de código. Você pode usar Skills de duas fontes:

Aspecto	Skills 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 via API de Skills
Disponibilidade	Disponível para todos os usuários	Privada para seu workspace

Ambas as fontes de skills são retornadas pelo endpoint List Skills (use o parâmetro source para filtrar). A forma 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 Anthropic do Console
Headers Beta:
- code-execution-2025-08-25 - Ativa execução de código (obrigatório para Skills)
- skills-2025-10-02 - Ativa API de Skills
- files-api-2025-04-14 - Para enviar/baixar arquivos para/do container
Ferramenta de execução de código ativada em suas solicitações

Usando Skills em Mensagens

Parâmetro Container

Skills são especificadas usando o parâmetro container na API de Mensagens. Você pode incluir até 8 Skills por solicitação. A estrutura é idêntica para Skills Anthropic e personalizadas—especifique o type e skill_id obrigatórios, e opcionalmente inclua version para fixar uma versão específica:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 API de Arquivos para baixar esses arquivos. Como funciona:

Skills criam arquivos durante a execução de código
A resposta inclui file_id para cada arquivo criado
Use a API de Arquivos para baixar o conteúdo real do arquivo
Salve localmente ou processe conforme necessário

Exemplo: Criando e baixando um arquivo Excel

import anthropic

client = anthropic.Anthropic()

# Passo 1: Use uma Skill para criar um arquivo
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

# Passo 2: Extraia 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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Passo 3: Baixe o arquivo usando a API de Arquivos
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

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

Operações adicionais da API de Arquivos:

# Obtenha metadados do arquivo
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Liste todos os arquivos
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete um arquivo
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

Para detalhes completos sobre a API de Arquivos, consulte a documentação da API de Arquivos.

Conversas Multi-Turno

Reutilize o mesmo container em várias mensagens especificando o ID do container:

# Primeira solicitação cria container
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Continue a conversa com o mesmo container
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reutilize 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 realizar operações que requerem múltiplos turnos. Trate razões de parada pause_turn:

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

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

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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"}]
    )

A resposta pode incluir uma razão de parada pause_turn, que indica que a API pausou uma operação de Skill de longa duração. Você pode fornecer a resposta como está em uma solicitação subsequente para deixar Claude continuar seu turno, ou modificar o conteúdo se desejar interromper a conversa e fornecer orientação adicional.

Usando Múltiplas Skills

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

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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

Envie sua Skill personalizada para disponibilizá-la em seu workspace. Você pode enviar usando um caminho de diretório ou objetos de arquivo individuais.

import anthropic

client = anthropic.Anthropic()

# Opção 1: Usando o auxiliar files_from_dir (apenas Python, recomendado)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# Opção 2: Usando um arquivo zip
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Opção 3: Usando tuplas de arquivo (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

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 tamanho total do upload deve ser inferior a 8MB
Frontmatter YAML: name (máximo 64 caracteres), description (máximo 1024 caracteres)

Para esquemas completos de solicitação/resposta, consulte a referência da API Create Skill.

Listando Skills

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

# Liste todas as Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# Liste apenas Skills personalizadas
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

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:

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Deletando uma Skill

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

# Passo 1: Delete todas as versões
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Passo 2: Delete a Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

Tentar deletar uma Skill com versões existentes retornará um erro 400.

Versionamento

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

Versões usam formato de data: 20251013
Novas versões 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

# Crie uma nova versão
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Use versão específica
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Use versão mais recente
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

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

Como Skills São Carregadas

Quando você especifica Skills em um container:

Descoberta de Metadados: Claude vê metadados para cada Skill (nome, descrição) no prompt do sistema
Carregamento de Arquivo: Arquivos de Skill são copiados para o container em /skills/{directory}/
Uso Automático: Claude carrega e usa automaticamente Skills quando relevante para sua solicitação
Composição: Múltiplas Skills se compõem para fluxos de trabalho complexos

A arquitetura de divulgação progressiva garante uso eficiente de contexto—Claude carrega apenas instruções completas de Skill quando necessário.

Casos de Uso

Skills Organizacionais

Marca & Comunicações

Aplique formatação específica da empresa (cores, fontes, layouts) a documentos
Gere comunicações seguindo templates organizacionais
Garanta diretrizes de marca consistentes em todos os outputs

Gerenciamento de Projetos

Estruture notas com formatos específicos da empresa (OKRs, decision logs)
Gere tarefas seguindo convenções de equipe
Crie recaps de reunião padronizados e atualizações de status

Operações de Negócios

Crie relatórios, propostas e análises padrão da empresa
Execute procedimentos analíticos específicos da empresa
Gere modelos financeiros seguindo templates organizacionais

Skills Pessoais

Criação de Conteúdo

Templates de documento personalizados
Formatação e estilo especializados
Geração de conteúdo específico do domínio

Análise de Dados

Pipelines de processamento de dados personalizados
Templates de visualização especializados
Métodos analíticos específicos da indústria

Desenvolvimento & Automação

Templates de geração de código
Frameworks de teste
Fluxos de trabalho de deployment

Exemplo: Modelagem Financeira

Combine Skills de Excel e análise DCF personalizada:

# Crie Skill de análise DCF personalizada
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"]
)

# Use com Excel para criar modelo financeiro
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Limites e Restrições

Limites de Solicitação

Máximo de Skills por solicitação: 8
Tamanho máximo de upload de Skill: 8MB (todos os arquivos combinados)
Limites de frontmatter YAML: name 64 caracteres, description 1024 caracteres

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 pode fazer chamadas de API externas
Sem instalação de pacote em tempo de execução - Apenas pacotes pré-instalados disponíveis
Ambiente isolado - Cada solicitação obtém um container novo

Consulte a documentação da ferramenta de execução de código para pacotes disponíveis.

Melhores Práticas

Quando Usar Múltiplas Skills

Combine Skills quando tarefas envolvem múltiplos tipos de documento 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 documento

Evite:

Incluir Skills não utilizadas (impacta performance)

Estratégia de Gerenciamento de Versão

Para produção:

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

Para desenvolvimento:

# Use latest para desenvolvimento ativo
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Sempre obtenha a mais nova
    }]
}

Considerações de Cache de Prompt

Ao usar cache de prompt, note que alterar a lista de Skills em seu container quebrará o cache:

# Primeira solicitação cria cache
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Adicionar/remover Skills quebra cache
response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"}  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Para melhor performance de cache, mantenha sua lista de Skills consistente entre solicitações.

Tratamento de Erros

Trate erros relacionados a Skills com elegância:

try:
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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}")
        # Trate erros específicos de skill
    else:
        raise

Próximos Passos

Referência da API

Referência completa da API com todos os endpoints

Guia de Autoria

Melhores práticas para escrever Skills eficazes

Ferramenta de Execução de Código

Aprenda sobre o ambiente de execução de código

Usando as APIs

Referência da API

SDKs

Exemplos

APIs de terceiros

Usando a Admin API

Suporte e configuração

​Links Rápidos

Comece com Agent Skills

Crie Skills Personalizadas

​Visão Geral

​Usando Skills

​Pré-requisitos

​Usando Skills em Mensagens

​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

​Deletando uma Skill

​Versionamento

​Como Skills São Carregadas

​Casos de Uso

​Skills Organizacionais

​Skills Pessoais

​Exemplo: Modelagem Financeira

​Limites e Restrições

​Limites de Solicitação

​Restrições de Ambiente

​Melhores Práticas

​Quando Usar Múltiplas Skills

​Estratégia de Gerenciamento de Versão

​Considerações de Cache de Prompt

​Tratamento de Erros

​Próximos Passos

Referência da API

Guia de Autoria

Ferramenta de Execução de Código

Links Rápidos

Visão Geral

Usando Skills

Pré-requisitos

Usando Skills em Mensagens

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

Deletando uma Skill

Versionamento

Como Skills São Carregadas

Casos de Uso

Skills Organizacionais

Skills Pessoais

Exemplo: Modelagem Financeira

Limites e Restrições

Limites de Solicitação

Restrições de Ambiente

Melhores Práticas

Quando Usar Múltiplas Skills

Estratégia de Gerenciamento de Versão

Considerações de Cache de Prompt

Tratamento de Erros

Próximos Passos