Usando Agent Skills com a API

Skills na 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 not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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 aprofundada da arquitetura e aplicações do mundo real de Agent Skills, leia o post do blog de engenharia: Equipping agents for the real world with Agent Skills.

Skills se integram com a 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, 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 Messages API 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 da API Claude do Console
Cabeçalhos Beta:
- code-execution-2025-08-25 - Ativa execução de código (obrigatório para Skills)
- skills-2025-10-02 - Ativa Skills API
- files-api-2025-04-14 - Para enviar/baixar arquivos para/do container
Ferramenta de execução de código ativada em suas requisições

Usando Skills em Messages

Parâmetro Container

Skills são especificadas usando o parâmetro container na Messages API. 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), eles retornam atributos file_id na resposta. Você deve usar a Files API para baixar esses arquivos.

Como funciona:

Skills criam arquivos durante a execução do código
A resposta inclui file_id para cada arquivo criado
Use a Files API 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 Files API:

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

Conversas Multi-Turno

Reutilize o mesmo contêiner em várias mensagens especificando o ID do contêiner:

Operações de Longa Duração

As Skills podem executar operações que exigem 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 requisição subsequente para permitir que Claude continue 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

Carregue 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 30 MB
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 solicitação/resposta, consulte a referência da API Criar Skill.

Listando Skills

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

Consulte a referência da API Listar 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 retorna 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 as 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 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 recaps 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 documentos 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 Excel e Skills de análise DCF personalizada:

Limites e Restrições

Limites de Requisição

Máximo de Skills por requisição: 8
Tamanho máximo de upload de Skill: 30 MB (todos os arquivos combinados)
Requisitos de frontmatter YAML:
- name: Máximo de 64 caracteres, apenas letras minúsculas/números/hífens, sem tags XML, sem palavras reservadas
- description: Máximo de 1024 caracteres, não vazio, sem tags XML

Restrições de Ambiente

Skills são executadas no contêiner 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 disponíveis
Ambiente isolado - Cada requisição obtém um contêiner 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 as 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 documentos

Evite:

Incluir Skills não utilizadas (impacta o 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 sobre Cache de Prompt

Ao usar cache de prompt, observe que alterar a lista de Skills no seu contêiner quebra o cache:

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

Tratamento de Erros

Trate erros relacionados a Skills com elegância:

Retenção de dados

Agent Skills não são cobertos por arranjos 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 de ZDR em todos os recursos, consulte Retenção de API e dados.

Próximas Etapas

Referência da API

Referência completa da API com todos os endpoints

Guia de Autoria

Melhores práticas para escrever Skills eficazes

client = anthropic.Anthropic()

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

client = anthropic.Anthropic()
file_id = "file_abc123"
# 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"])

# Primeira requisição cria contêiner
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

# Continuar conversa com o mesmo contêiner
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-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reutilizar contêiner
        "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-7",
    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"}],
)

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

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# Step 1: Delete all versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --format yaml \
  | tr -d '"' \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Step 2: Delete the Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --format yaml)

# Use specific version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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

# Use latest version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
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

# 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-opus-4-7",
    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-opus-4-7",
    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-opus-4-7",
    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"}],
)

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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