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 requisiçã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

This feature is in beta and is not covered by Zero Data Retention (ZDR) arrangements. Beta features are excluded from ZDR.

Links Rápidos

Comece com Agent Skills

Crie sua primeira Skill

Criar 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 exigem 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 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
Cabeçalhos 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 enviar/baixar arquivos para/do container
Ferramenta de execução de código habilitada em suas requisiçõ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 requisiçã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 real do arquivo
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 exigem múltiplos turnos. Trate razões de parada pause_turn:

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 requisiçã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 requisiçã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 enviar 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 envio deve ser inferior a 8MB
Requisitos de 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 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 Criar Versão de Skill 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 Skills automaticamente quando relevante para sua solicitação
Composição: Múltiplas Skills se compõem juntas 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 e Comunicações

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

Gerenciamento de Projetos

Estruturar notas com formatos específicos da empresa (OKRs, logs de decisão)
Gerar tarefas seguindo convenções da equipe
Criar recapitulações de reuniões e atualizações de status padronizadas

Operações Comerciais

Criar relatórios, propostas e análises padrão da empresa
Executar procedimentos analíticos específicos da empresa
Gerar 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 e 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 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 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:

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

Para desenvolvimento:

# Usar latest para desenvolvimento ativo
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Sempre obter a mais recente
        }
    ]
}

Considerações de Cache de Prompt

Ao usar cache de prompt, note 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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
    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-opus-4-6",
        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-opus-4-6",
    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"]
)

# Criar 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"],
)

# Usar versão específica
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Usar versão mais recente
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Criar 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"],
)

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

# Primeira solicitação cria cache
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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.beta.messages.create(
    model="claude-opus-4-6",
    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-opus-4-6",
        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}")
        # Tratar erros específicos de Skill
    else:
        raise