MensagensHabilidades

Usando Agent Skills com a API

Aprenda como usar Agent Skills para estender as capacidades do Claude através da API.

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

Para a 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

Este recurso não é elegível para Zero Data Retention (ZDR). Os dados são retidos de acordo com a política de retenção padrão do recurso.

Links rápidos

Comece a usar Agent Skills

Crie sua primeira Skill

Crie Skills personalizadas

Melhores práticas para criar Skills

Visão geral

Para um aprofundamento na arquitetura e aplicações reais 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, o formato de integração é idêntico: 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 origem. Você especifica Skills no parâmetro container com um skill_id, type e, opcionalmente, version, e elas são executadas no ambiente de execução de código.

Você pode usar Skills de duas origens:

Aspecto	Skills da 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 epoch: `1759178010641129` ou `latest`
Gerenciamento	Pré-construídas e mantidas pela Anthropic	Envie e gerencie através da Skills API
Disponibilidade	Disponíveis para todos os usuários	Privadas ao seu workspace

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:

Chave de API do Claude 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 a Skills API
- files-api-2025-04-14 - Para enviar/baixar arquivos de/para o container
Ferramenta de execução de código habilitada 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 da Anthropic e 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.beta.messages.create(
    model="claude-opus-4-8",
    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 Files API 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 Files API para baixar o conteúdo real do arquivo
Salve localmente ou processe conforme necessário

Exemplo: Criando e baixando um arquivo Excel

client = anthropic.Anthropic()

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


# Etapa 2: Extraia 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":
                # lista com tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Etapa 3: Baixe o arquivo usando a Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Etapa 4: Salve no 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_abc123"
# Obter metadados do arquivo
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Listar todos os arquivos
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Excluir um arquivo
client.beta.files.delete(file_id=file_id)

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

Conversas multi-turno

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

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

Operações de longa duração

Skills podem executar operações que requerem múltiplos turnos. Trate os stop reasons pause_turn:

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

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

# Lidar com 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-8",
        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 um stop reason pause_turn, que indica que a API pausou uma operação de Skill de longa duração. Você pode fornecer a resposta de volta como está em uma requisição subsequente para permitir que o 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 requisição para lidar com fluxos de trabalho complexos:

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

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 suporte. Consulte Comece a usar Agent Skills na API para criar um, e a lista de Requisitos após os exemplos para as restrições completas.

Envie sua Skill personalizada para disponibilizá-la em seu workspace. Você pode enviar um arquivo zip ou objetos de arquivo individuais; o SDK Python fornece adicionalmente um helper files_from_dir que aceita um caminho de diretório.

# Opção 1: Fazer upload de arquivos individuais (uma flag --file por arquivo)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Opção 2: Fazer upload de um arquivo zip
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

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

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

Excluindo uma Skill

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

# Etapa 1: Excluir todas as versões
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Etapa 2: Excluir a Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Tentar excluir uma Skill com versões existentes retorna um erro 400.

Versionamento

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

Skills da Anthropic:

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:

Timestamps epoch gerados automaticamente: 1759178010641129
Use "latest" para sempre obter a versão mais recente
Crie novas versões ao atualizar arquivos de Skill

# Criar uma nova versão
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# Usar versão específica
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
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

# Usar a versão mais recente
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
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:

Descoberta de metadados: Claude vê os metadados de cada Skill (nome, descrição) no prompt do sistema
Carregamento de arquivos: Os arquivos da Skill são copiados para o container em /skills/{directory}/
Uso automático: Claude carrega e usa Skills automaticamente quando relevantes para sua requisiçã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 só carrega as instruções completas da 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 todas as saídas

Gerenciamento de projetos

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

Operações de negócios

Criar relatórios, propostas e análises no 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 estilização especializadas
Geração de conteúdo específico de domínio

Análise de dados

Pipelines de processamento de dados personalizados
Templates de visualização especializados
Métodos analíticos específicos do setor

Desenvolvimento e 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 de análise DCF personalizada:

# Criar Skill personalizada de análise DCF
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"),
)

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

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

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 de API externas
Sem instalação de pacotes em tempo de execução: Apenas pacotes pré-instalados estão disponíveis
Ambiente isolado: Containers são isolados; um novo container é criado a menos que você especifique um ID de container existente

Consulte Ferramenta de execução de código para 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ções (PowerPoint)
Geração de relatórios (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

Para produção:

# Fixe em versões específicas para garantir estabilidade
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Para desenvolvimento:

# Use latest para desenvolvimento ativo
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 em seu container invalida o cache:

# A primeira requisição cria o cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 invalida o cache
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 desempenho de cache, mantenha sua lista de Skills consistente entre requisições.

Tratamento de erros

Trate erros relacionados a Skills de forma adequada:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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}")
        # Trata erros específicos da skill
    else:
        raise

Retenção de dados

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

Próximos passos

Referência da API

Referência completa da API com todos os endpoints

Guia de criação

Melhores práticas para escrever Skills eficazes

Ferramenta de execução de código

Saiba mais sobre o ambiente de execução de código

Was this page helpful?

MensagensHabilidades

Usando Agent Skills com a API

Aprenda como usar Agent Skills para estender as capacidades do Claude através da API.

Para a 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

Este recurso não é elegível para Zero Data Retention (ZDR). Os dados são retidos de acordo com a política de retenção padrão do recurso.

Links rápidos

Comece a usar Agent Skills

Crie sua primeira Skill

Crie Skills personalizadas

Melhores práticas para criar Skills

Visão geral

Para um aprofundamento na arquitetura e aplicações reais de Agent Skills, leia o post do blog de engenharia: Equipping agents for the real world with Agent Skills.

Usando Skills

Você pode usar Skills de duas origens:

Aspecto	Skills da 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 epoch: `1759178010641129` ou `latest`
Gerenciamento	Pré-construídas e mantidas pela Anthropic	Envie e gerencie através da Skills API
Disponibilidade	Disponíveis para todos os usuários	Privadas ao seu workspace

Pré-requisitos

Para usar Skills, você precisa de:

Chave de API do Claude 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 a Skills API
- files-api-2025-04-14 - Para enviar/baixar arquivos de/para o container
Ferramenta de execução de código habilitada 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 da Anthropic e 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.beta.messages.create(
    model="claude-opus-4-8",
    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 Files API 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 Files API para baixar o conteúdo real do arquivo
Salve localmente ou processe conforme necessário

Exemplo: Criando e baixando um arquivo Excel

client = anthropic.Anthropic()

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


# Etapa 2: Extraia 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":
                # lista com tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Etapa 3: Baixe o arquivo usando a Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Etapa 4: Salve no 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_abc123"
# Obter metadados do arquivo
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Listar todos os arquivos
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Excluir um arquivo
client.beta.files.delete(file_id=file_id)

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

Conversas multi-turno

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

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

Operações de longa duração

Skills podem executar operações que requerem múltiplos turnos. Trate os stop reasons pause_turn:

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

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

# Lidar com 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-8",
        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"}],
    )

Usando múltiplas Skills

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

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

# Opção 1: Fazer upload de arquivos individuais (uma flag --file por arquivo)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Opção 2: Fazer upload de um arquivo zip
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

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

# Listar todas as Skills
ant beta:skills list

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

Excluindo uma Skill

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

# Etapa 1: Excluir todas as versões
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Etapa 2: Excluir a Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Tentar excluir uma Skill com versões existentes retorna um erro 400.

Versionamento

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

Skills da Anthropic:

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:

Timestamps epoch gerados automaticamente: 1759178010641129
Use "latest" para sempre obter a versão mais recente
Crie novas versões ao atualizar arquivos de Skill

# Criar uma nova versão
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# Usar versão específica
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
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

# Usar a versão mais recente
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
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:

Descoberta de metadados: Claude vê os metadados de cada Skill (nome, descrição) no prompt do sistema
Carregamento de arquivos: Os arquivos da Skill são copiados para o container em /skills/{directory}/
Uso automático: Claude carrega e usa Skills automaticamente quando relevantes para sua requisiçã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 só carrega as instruções completas da 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 todas as saídas

Gerenciamento de projetos

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

Operações de negócios

Criar relatórios, propostas e análises no 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 estilização especializadas
Geração de conteúdo específico de domínio

Análise de dados

Pipelines de processamento de dados personalizados
Templates de visualização especializados
Métodos analíticos específicos do setor

Desenvolvimento e 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 de análise DCF personalizada:

# Criar Skill personalizada de análise DCF
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"),
)

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

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

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 de API externas
Sem instalação de pacotes em tempo de execução: Apenas pacotes pré-instalados estão disponíveis
Ambiente isolado: Containers são isolados; um novo container é criado a menos que você especifique um ID de container existente

Consulte Ferramenta de execução de código para 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ções (PowerPoint)
Geração de relatórios (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

Para produção:

# Fixe em versões específicas para garantir estabilidade
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Para desenvolvimento:

# Use latest para desenvolvimento ativo
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 em seu container invalida o cache:

# A primeira requisição cria o cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 invalida o cache
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 desempenho de cache, mantenha sua lista de Skills consistente entre requisições.

Tratamento de erros

Trate erros relacionados a Skills de forma adequada:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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}")
        # Trata erros específicos da skill
    else:
        raise

Retenção de dados

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

Próximos passos

Referência da API

Referência completa da API com todos os endpoints

Guia de criação

Melhores práticas para escrever Skills eficazes

Ferramenta de execução de código

Saiba mais sobre o ambiente de execução de código

Was this page helpful?

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

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

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Skills organizacionais

Skills pessoais

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

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

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Skills organizacionais

Skills pessoais

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

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

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Skills organizacionais

Skills pessoais

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos

Links rápidos

Visão geral

Usando Skills

Pré-requisitos

Usando Skills em Messages

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

Excluindo uma Skill

Versionamento

Como as Skills são carregadas

Casos de uso

Skills organizacionais

Skills pessoais

Exemplo: modelagem financeira

Limites e restrições

Limites de requisição

Restrições de ambiente

Melhores práticas

Quando usar múltiplas Skills

Estratégia de gerenciamento de versões

Considerações sobre cache de prompt

Tratamento de erros

Retenção de dados

Próximos passos