Claude Skills API Lançamento Geral: O Que Mudou e Como Usar

A API Claude Skills está geralmente disponível a partir de 20 de agosto de 2026. Agora você pode criar, versionar e gerenciar habilidades personalizadas através de https://api.anthropic.com/v1/skills com cabeçalhos padrão, sem necessidade de flag beta, e executá-las dentro do sandbox de código de Claude sem ter que hospedar nada. A Anthropic lançou a disponibilidade geral (GA) em uma única onda com o uso de computador, a nova ferramenta de navegador e a API Files, enquadradas no anúncio como a pilha de produção para construção de agentes na Plataforma Claude.

Se o conceito de habilidades é novo para você, nosso guia para Claude Skills aborda a ideia desde o início. Este artigo trata da camada da API: os endpoints, o modelo de versionamento, o formato da requisição que carrega as habilidades em uma chamada de Mensagens, e os desafios (escopo de workspace, versionamento de snapshot) que a GA não suavizou. Como tudo é HTTP puro, cada chamada aqui pode ser construída e testada regressivamente no Apidog enquanto você acompanha.

botão

Uma revisão rápida de 30 segundos: o que é uma habilidade

Uma habilidade é uma pasta. Em seu nível superior, reside um arquivo SKILL.md com metadados YAML contendo um name e uma description; ao redor dele, ficam quaisquer scripts, modelos e arquivos de referência que a tarefa precise. Quando uma requisição inclui a habilidade, Claude carrega as instruções apenas quando a tarefa as exige, e executa quaisquer scripts empacotados em seu ambiente de código em sandbox.

Os metadados possuem regras de validação reais:

name: máximo de 64 caracteres, apenas letras minúsculas, números e hifens. Sem tags XML, e as palavras reservadas “anthropic” e “claude” são rejeitadas.
description: não vazio, máximo de 1024 caracteres.
Um display_name opcional (até 255 caracteres) pode ser amigável ao usuário.
O upload completo deve ter menos de 30 MB descompactado.

As habilidades vêm de duas fontes. Habilidades gerenciadas pela Anthropic (type: "anthropic") são pré-construídas com IDs curtos como pptx, xlsx, docx e pdf, e usam versões baseadas em datas, como 20251013. Habilidades personalizadas (type: "custom") são suas: carregadas através da API, privadas ao seu workspace, com IDs gerados como skill_01AbCdEfGhIjKlMnOpQrStUv.

O que a GA realmente mudou

Três coisas são novas ou foram solidificadas a partir de 20 de agosto de 2026:

Sem cabeçalho beta. A API Skills funciona na API Claude com apenas x-api-key e anthropic-version: 2023-06-01.
Um fluxo de upload e versionamento mais simples. A Anthropic descreve a GA como trazendo “uma API mais simples para upload e versionamento” de habilidades personalizadas. As versões são recursos de primeira classe com seus próprios endpoints.
Mais plataformas. A API Skills está disponível através do Microsoft Foundry, bem como da API Claude. As habilidades são executadas no sandbox gerenciado de Claude, então ainda não há infraestrutura do seu lado.

O restante da onda da GA também é importante para os usuários de habilidades: as habilidades frequentemente geram arquivos (uma apresentação, uma planilha preenchida), e essas saídas retornam através da recém-disponibilizada API Files.

A superfície do endpoint

Tudo reside em /v1/skills:

Operação	Endpoint
Criar uma habilidade	`POST /v1/skills`
Listar habilidades	`GET /v1/skills`
Recuperar uma habilidade	`GET /v1/skills/{skill_id}`
Excluir uma habilidade	`DELETE /v1/skills/{skill_id}`
Criar uma nova versão	`POST /v1/skills/{skill_id}/versions`
Listar versões	`GET /v1/skills/{skill_id}/versions`

Criar uma habilidade carrega seu conjunto completo de arquivos; criar uma versão faz o mesmo em relação a um ID de habilidade existente. Em um projeto Apidog, isso se mapeia de forma limpa para uma pasta de seis requisições salvas com {{skill_id}} e {{skill_version}} como variáveis de ambiente, então promover uma nova versão através dos ambientes de desenvolvimento e produção é uma mudança de variável, não uma edição de requisição.

Fazendo upload de uma habilidade personalizada

Uma habilidade personalizada mínima consiste em duas coisas: a pasta e a chamada de upload. Digamos que você mantenha uma habilidade de relatório de marca em seu repositório:

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

Com SKILL.md começando assim:

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

Faça o upload postando os arquivos como dados de formulário multipart:

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

A resposta retorna o skill_id gerado e o ID skver_* da primeira versão. Armazene ambos; o ID da habilidade vai em suas requisições de Mensagens, e o ID da versão é seu ponto de ancoragem para rollback. Verifique os nomes exatos dos campos multipart na referência da API Skills para a sua versão do SDK, já que os helpers do SDK tipado encapsulam essa chamada na maioria das linguagens.

Observe a descrição: ela se parece com uma regra de roteamento. Claude decide se deve carregar uma habilidade lendo esse campo, então uma descrição que lista as frases de gatilho que seus usuários dizem supera um rótulo de uma linha todas as vezes.

Usando uma habilidade em uma requisição de Mensagens

As habilidades não se anexam a uma requisição por si mesmas. Elas utilizam a ferramenta de execução de código, declarada através do parâmetro container:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

As regras que governam este bloco:

A ferramenta de execução de código deve estar habilitada em tools, já que as habilidades são executadas dentro desse sandbox. O suporte a modelos segue a lista de compatibilidade da ferramenta de execução de código.
Até 20 habilidades por requisição. Claude lê a descrição de cada habilidade e carrega instruções apenas para aquelas que a tarefa precisa.
O fixar da versão está sob seu controle. "latest" aponta para a versão mais recente; um ID skver_* fixado (ou versão de data para habilidades da Anthropic) congela o comportamento. Fixe em produção, deixe flutuar em desenvolvimento.

Quando uma habilidade produz um documento, a resposta contém um file_id que você baixa através do GET /v1/files/{file_id}/content da API Files. Essa interação de duas APIs (Skills para gerar, Files para recuperar) é o loop de produção central.

Versionamento: snapshots, não diffs

O modelo de versionamento é a parte que a maioria das equipes erra na primeira tentativa. Uma nova versão é um snapshot completo, não um delta. Quando você POST /v1/skills/{skill_id}/versions, você faz o upload de todo o conjunto de arquivos da habilidade novamente; arquivos que você omitir não serão transferidos da versão anterior. O name no SKILL.md da nova versão também deve corresponder ao nome existente da habilidade.

Trate as pastas de habilidades como artefatos de build: mantenha a fonte da verdade em seu repositório, empacote a pasta inteira na CI e a envie como uma nova versão. O rollback é então trivial, já que as versões antigas permanecem acessíveis por seus IDs skver_* e um incidente de produção é corrigido fixando novamente uma string.

Escopo do workspace: a armadilha multi-tenant

Habilidades personalizadas são acessíveis a todo o seu workspace. Elas não são limitadas a um usuário final, uma conversa ou uma sessão, e todas as chaves de API no workspace as compartilham. Se você executa um produto multi-tenant onde os tenants fazem upload de suas próprias habilidades, um único workspace é um vazamento de dados prestes a acontecer.

A solução é a mesma que para a API Files: crie um workspace separado por tenant. O workspace é o limite de isolamento, e cada organização tem direito a até 100 workspaces antes de precisar falar com uma equipe de contas. Chaves, arquivos e habilidades herdam esse limite, então uma decisão isola os três.

Habilidades de longa duração: pause_turn e reuso de container

As execuções de habilidades podem durar mais de um único turno do modelo. Dois mecanismos lidam com isso:

pause_turn: quando uma resposta para com stop_reason: "pause_turn", anexe o conteúdo do assistente ao seu histórico de mensagens e chame novamente, passando o mesmo container.id. O sandbox continua de onde parou.
Reuso de container: o objeto container aceita um id de uma resposta anterior, mantendo arquivos instalados e estado ativos em uma conversa de múltiplos turnos. Isso significa que uma habilidade pode construir uma planilha no turno um e revisá-la no turno três sem regenerar do zero.

Ambos os padrões são sequências HTTP com estado, o que os torna difíceis de testar manualmente e agradáveis de testar como um cenário Apidog: a requisição um verifica stop_reason, um script eleva container.id para uma variável, a requisição dois o reutiliza, e o passo final verifica se o file_id gerado é baixado corretamente. O CLI do Apidog executa o mesmo cenário na CI, então uma atualização de versão de habilidade não pode quebrar silenciosamente seu pipeline. Se você quiser ver como as habilidades se comportam dentro do ecossistema de outro fornecedor para comparação, analisamos a habilidade Claude do Postman em uma revisão anterior.

Onde é executado

Na GA, a API Skills está disponível na API Claude e através do Microsoft Foundry. As habilidades são executadas no sandbox da Anthropic independentemente, então “implantação” é um upload, e não há imagem de container, patching em tempo de execução, nem controle de escalonamento do seu lado. Observe a dependência do modelo em vez de uma plataforma: a requisição deve usar um modelo que a ferramenta de execução de código suporte, como claude-opus-5 nos exemplos acima. Nosso guia da API Claude Opus 5 cobre os fundamentos da requisição desse modelo se você estiver começando.

FAQ

Ainda preciso do cabeçalho beta de habilidades? Não. Desde 20 de agosto de 2026, /v1/skills e o parâmetro container.skills funcionam com cabeçalhos padrão na API Claude. Remova quaisquer flags beta fixadas ao atualizar seu SDK.

Uma habilidade pode chamar APIs externas enquanto é executada? As habilidades são executadas dentro do sandbox de código de Claude com as restrições de rede da ferramenta de execução de código. Empacote o que a habilidade precisa em sua pasta em vez de presumir egressos abertos, e mantenha a lógica de chamada de API em sua camada de aplicação, onde você pode testá-la adequadamente.

Quantas habilidades uma requisição pode carregar? Até 20. Claude lê os metadados de description de cada habilidade para decidir quais delas a tarefa precisa, então as descrições são cruciais: escreva-as como regras de roteamento, não como texto de marketing.

Qual a diferença entre isso e as habilidades do Claude Code? Mesmo conceito, tempo de execução diferente. Claude Code descobre pastas de habilidades em seu sistema de arquivos; a API Skills as hospeda no lado do servidor, versionadas, para chamadas da API de Mensagens. O formato da pasta com metadados SKILL.md é compartilhado, então uma habilidade que você escreveu para Claude Code geralmente é portada com poucas alterações.

Conclusão

A GA transforma as habilidades de um experimento em uma superfície operacional: seis endpoints, versionamento de snapshots, isolamento de workspace e uma transição limpa para a API Files para as saídas. As equipes que obtêm valor mais rapidamente tratam as habilidades como qualquer outro artefato implantável, o que significa empacotamento na CI, versões fixadas em produção e testes automatizados em torno do ciclo de vida do contêiner. Modele os seis endpoints no Apidog, conecte a atualização da versão a um cenário de teste, e você saberá que uma versão de habilidade com problemas quebrou seu gerador de apresentações antes que seus usuários percebam. Baixe o Apidog gratuitamente e construa o arnes em uma tarde.