Habilidades do agente

Usando Agent Skills com a API

Aprenda como usar Agent Skills para estender os recursos do Claude através da 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`

Ambas as fontes de skill 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 - Habilita execução de código (obrigatório para Skills)
- skills-2025-10-02 - Habilita API de Skills
- files-api-2025-04-14 - Para fazer upload/download de arquivos para/do container
Ferramenta de execução de código habilitada 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:

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 do arquivo real
Salve localmente ou processe conforme necessário

Exemplo: Criando e baixando um arquivo Excel

Operações adicionais da API de Arquivos:

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:

Operações de Longa Duração

Skills podem executar operações que requerem múltiplos turnos. Trate os motivos de parada pause_turn:

A resposta pode incluir um motivo de parada pause_turn, que indica que a API pausou uma operação de Skill de longa duração. Você pode fornecer a resposta 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:

Gerenciando Skills Personalizadas

Criando uma Skill

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

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
Requisitos de frontmatter YAML:
- name: Máximo 64 caracteres, apenas letras minúsculas/números/hífens, sem tags XML, sem palavras reservadas ("anthropic", "claude")
- description: Máximo 1024 caracteres, não vazio, sem tags XML

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:

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:

Deletando uma Skill

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

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

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 Arquivos: 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, logs de decisão)
Gere tarefas seguindo convenções da equipe
Crie recapitulações de reuniões e atualizações de status padronizadas

Operações Comerciais

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 implantação

Exemplo: Modelagem Financeira

Combine Skills de Excel e análise DCF personalizada:

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)
Requisitos de frontmatter YAML:
- name: Máximo 64 caracteres, apenas letras minúsculas/números/hífens, sem tags XML, sem palavras reservadas
- description: Máximo 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 pode fazer chamadas de API externas
Sem instalação de pacotes em tempo de execução - Apenas pacotes pré-instalados disponíveis
Ambiente isolado - Cada solicitação obtém um container fresco

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

Evite:

Incluir Skills não utilizadas (impacta desempenho)

Estratégia de Gerenciamento de Versão

Para produção:

# Pin to specific versions for stability
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Specific version
    }]
}

Para desenvolvimento:

# Use latest for active development
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Always get newest
    }]
}

Considerações de Cache de Prompt

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

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

Tratamento de Erros

Trate erros relacionados a Skills com elegância:

Próximos Passos

Referência da API

Referência completa da API com todos os endpoints

import anthropic

client = anthropic.Anthropic()

response = client.beta.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"
    }]
)

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.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"}]
)

# Step 2: Extract file IDs from the response
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

# Step 3: Download the file using Files API
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"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

# Get file metadata
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")

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

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

# First request creates container
response1 = client.beta.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 conversation with same container
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

response2 = client.beta.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,  # Reuse container
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

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

response = client.beta.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"}]
)

# Handle pause_turn for long operations
for i 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-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"}]
    )

response = client.beta.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"
    }]
)

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
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"]
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Option 3: Using file tuples (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}")

# List all 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})")

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

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}")

# Step 1: Delete all versions
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"]
    )

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

# Create a new version
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 specific version
response = client.beta.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 latest version
response = client.beta.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"}]
)

# Create custom DCF analysis Skill
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 with Excel to create financial model
response = client.beta.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"}]
)

# First request creates cache
response1 = client.beta.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"}]
)

# Adding/removing Skills breaks cache
response2 = client.beta.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"}]
)

try:
    response = client.beta.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}")
        # Handle skill-specific errors
    else:
        raise