Claude Skills API: o que mudou com o GA e como usar

Em 20 de agosto de 2026, a Anthropic colocou a Claude Skills API, o computer use e a Files API em disponibilidade geral. Saem os headers de beta; entram várias ações por turno no computer use e uma nova ferramenta de browser use. Mas o GA não resolve um ponto importante: as skills continuam sendo executadas apenas quando o Claude decide acioná-las. Portanto, o versionamento fixado e o desenho da ativação ainda são responsabilidade sua.

O que realmente mudou com o GA em 20 de agosto

As integrações beta já existentes continuam funcionando durante a migração. Além disso, o post de lançamento da Anthropic reúne mudanças concretas:

• Fim dos headers de beta. O atual guia de skills traz apenas dois pré-requisitos: uma chave da Claude API e a execução de código habilitada na requisição. Os headers beta exigidos por tutoriais anteriores ao GA não aparecem mais na documentação.
• Várias ações por turno. A ferramenta atualizada de computer use realiza diversas ações a cada chamada do modelo — clique, digitação, tecla e captura de tela — em vez de apenas uma. A conta @ClaudeDevs relata que clientes do acesso antecipado tiveram 20–40% menos idas e vindas por tarefa.
• Uma ferramenta de browser use. Ela combina capturas de tela e a estrutura da página para que o agente encontre um campo ou botão específico, sem depender de coordenadas de pixels. O foco são portais web, como os de envio de solicitações de seguro.
• Mais escala na Files API. São 1 TB de armazenamento por organização, limites de taxa 5x maiores — 500 RPM segundo a thread da @ClaudeDevs — e expiração automática de arquivos.
• Caminho para conformidade. O computer use agora pode ser usado em cargas de trabalho reguladas pela HIPAA sob o BAA da Anthropic.
• Disponibilidade em nuvem. A Skills API e a Files API também estão disponíveis via Microsoft Foundry. As ferramentas atualizadas de computer use e browser use estão "coming soon" para o Vertex AI, sem data informada.

Como as três APIs trabalham juntas

O exemplo de agente de sinistros da Anthropic mostra o fluxo completo: buscar um documento de entrada pelo ID de arquivo com a Files API, aplicar uma skill com o procedimento de preenchimento usando a Skills API, concluir o portal da seguradora com browser use no computer use e, por fim, salvar a confirmação como arquivo. O upload é feito uma vez, e as chamadas posteriores fazem referência ao file_id, sem reenviar o documento em cada requisição.

Os dois conjuntos de números divulgados no lançamento vêm de fornecedores. No post de lançamento, o engenheiro de pesquisa Davide Locatelli informou que o fluxo mais longo de sinistros caiu de 32 minutos para 13 minutos, com a conclusão chegando a 100%. Separadamente, David Mlčoch, cofundador da Asteroid, testou fluxos de computer use para saúde durante o acesso antecipado:

"32-52% fewer model calls, 25-32% lower cost per task, 100% completion on every workflow, up from 77%" — @MlcochDavid

Como chamar a Claude Skills API pela Messages API

Para anexar uma skill, basta um parâmetro: o objeto container na requisição da Messages API, contendo uma matriz skills. Cada item informa o type — anthropic ou custom —, o skill_id e, opcionalmente, a version.

Segundo o guia oficial de skills, a mecânica em torno desse parâmetro é a seguinte:

• A execução de código precisa estar habilitada, e o modelo deve oferecer suporte a ela. Os exemplos do guia usam claude-opus-5, a ferramenta code_execution_20250825 e max_tokens=4096.
• Uma única requisição aceita até 20 skills.
• As skills são executadas no sandbox de execução de código da Anthropic: sem acesso à rede, sem instalação de pacotes em tempo de execução e com um novo container a cada requisição, a menos que você reutilize o container.id retornado entre turnos. Cada resposta inclui expires_at.
• Você não hospeda os arquivos da skill: a Anthropic os executa no container.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=[{"type": "code_execution_20250825"}],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "20251013"},
            {"type": "custom", "skill_id": "skill_01...", "version": "skver_01..."},
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue summary"}],
)

Os documentos de entrada seguem o caminho inverso: primeiro, envie-os pela Files API; depois, faça referência a eles em um bloco de upload do container. A requisição mantém o formato padrão da Anthropic Messages API, portanto funciona tanto com uma chave direta quanto com um relay compatível com Anthropic, como a Claude API da AIReiter.

As skills integradas usam IDs curtos e legíveis, como pptx, xlsx, docx e pdf, além de versões em formato de data, como 20251013 ou latest. Já as skills personalizadas recebem IDs skill_01..., vinculados ao seu workspace.

Como publicar uma Skill personalizada sem esbarrar nas regras

Uma skill personalizada é um diretório cujo SKILL.md na raiz traz um frontmatter YAML com name e description. Scripts e arquivos de referência podem ficar ao lado dele. O menor arquivo funcional tem esta estrutura:

---
name: eu-claims-filing
description: Use when filing or amending EU insurance claims. Loads the
  carrier-specific submission procedure, required fields, and rejection
  codes before filling any portal form.
---

# EU claims filing procedure
1. Pull the intake document by file_id ...

O upload pode ser feito como arquivo ZIP ou por arquivos individuais — o SDK Python oferece files_from_dir. Antes mesmo de a skill rodar, a Anthropic aplica limites rígidos, todos listados no guia de skills:

O gerenciamento é feito pela CLI ant ou pelos endpoints de API usados por ela, segundo o mesmo guia. O caminho do arquivo até uma versão fixada é este:

ant skills create ./eu-claims-filing   # returns skill_01...
ant skills:versions create skill_01...  # returns skver_01... — pin this in production

Dois comportamentos costumam surpreender as equipes na primeira utilização: uma nova versão é um snapshot completo — é preciso reenviar todos os arquivos, pois o que ficar de fora não é mantido — e excluir uma skill remove todas as versões dela.

Checklist de produção: fixe, isole e aproveite o cache

Em produção, os problemas mais comuns envolvem versões mutáveis, permissões que abrangem todo o workspace e perdas de cache. O guia de skills é explícito sobre os três pontos.

1. Fixe as versões. Usando latest, ou sem informar versão, qualquer pessoa com acesso ao workspace que enviar uma nova versão altera imediatamente o que seu agente implantado executa. Em produção, fixe IDs skver_...; deixe latest para o desenvolvimento ativo.
2. Considere o workspace como limite de tenant. Toda chave de API em um workspace pode ler, invocar e excluir todas as skills personalizadas nele. O isolamento ocorre por workspace, não por usuário ou sessão. Aplicações multi-tenant devem usar um workspace por tenant, lembrando do limite padrão de 100 workspaces.
3. Mantenha a lista de skills estável para o cache. Alterar a lista de skills, inclusive sua ordem, muda o prefixo do prompt de sistema e invalida o cache de prompt. Fixar versões personalizadas também protege esse prefixo, pois uma nova publicação de latest poderia reescrever a descrição. Em cobrança por token, uma lista de skills que varia entre requisições elimina silenciosamente a economia dos acertos de cache.
4. Trate pause_turn. Skills de longa duração retornam stop_reason: "pause_turn". Para continuar, reenvie o conteúdo retornado em uma requisição posterior; para interromper, modifique a conversa.
5. Entenda sua política de retenção. Agent Skills não são cobertas por acordos de retenção zero de dados. As definições das skills e os dados de execução seguem a política de retenção padrão da Anthropic. Com a Compliance API habilitada, o Activity Feed registra a criação e a exclusão de skills e versões de skills, mas apenas a partir da ativação.
6. Capture os erros certos. Envolva as chamadas para capturar anthropic.BadRequestError e separe falhas relacionadas a skills dos demais erros de requisição inválida.
7. Não anexe skills sem uso. A documentação afirma isso diretamente: incluir skills não utilizadas prejudica o desempenho.

O problema de ativação que nenhuma mudança na API resolve

O GA melhorou a infraestrutura em torno das skills, não a forma como o Claude escolhe usá-las. Uma preocupação recorrente nas discussões de usuários abaixo é que skills funcionam como procedimentos acionados por gatilhos, e não como um segundo prompt de sistema.

"My problem with Claude Skills is that they are not skills. Nothing forces Claude to actually use them. Claude does whatever it wants... These are just md files." — @Yampeleg, escrito antes do GA; o mecanismo de invocação não mudou

A thread no r/ClaudeAI sobre se as skills realmente funcionam resume os ajustes práticos:

"userstyle gets prepended every turn but skills only fire when claude decides to invoke based on the description." — u/samxu01

"Skills must have a simple, clear metadata description that also focuses on an action that Claude is doing." — u/Chadum

Essas discussões apontam quatro regras:

• Escreva a descrição com foco nas frases de gatilho e na ação, não em uma persona.
• Coloque no corpo as etapas, verificações, regras e escolhas de ferramentas. O teste de u/MartinMystikJonas: "If your skills define steps agent should do, things it should check, rules it should follow and tools it should use then it is useful."
• Codifique o que o Claude não faz bem de forma nativa, como recomenda u/Actual_Committee4670.
• Leve requisitos sempre ativos para o prompt de sistema ou o CLAUDE.md — adicionados em todo turno, como observou u/samxu01 — e deixe hooks para momentos do ciclo de vida, como antes de um commit.

Perguntas rápidas

Ainda preciso de headers beta para a Skills API?

Não. Desde o GA de 20 de agosto de 2026, os pré-requisitos são uma chave da Claude API e a execução de código habilitada. A documentação atual não exige header beta.

As skills consomem minha janela de contexto?

Inicialmente, apenas os metadados. Segundo o guia de skills, o Claude recebe o frontmatter de cada skill logo de início, copia os arquivos para o container e só carrega as instruções completas quando a tarefa exige isso. É por isso que a documentação alerta contra anexar skills não utilizadas.

Qual é a diferença entre Skill e MCP?

Uma skill é um pacote de instruções e scripts executado no sandbox do Claude, sem acesso à rede. O MCP conecta o Claude a sistemas externos em tempo real — distinção apresentada pela Anthropic em sua visão geral de skills. Um fluxo de sinistros pode usar ambos: um servidor MCP para o banco de dados de apólices e uma skill para o procedimento de preenchimento.

Um mesmo SKILL.md pode rodar no Claude.ai, Claude Code e na API?

O formato SKILL.md é compartilhado, mas a entrega muda conforme a superfície: skills enviadas ao workspace na API, diretórios .claude/skills no Claude Code e uploads no nível do plano no aplicativo Claude.ai.

A Skills API funciona com retenção zero de dados?

Não. Agent Skills ficam fora dos acordos de retenção zero de dados; as definições das skills e os dados de execução seguem a política de retenção padrão.

Qual mecanismo usar em cada necessidade

A escolha depende do momento da invocação:

O dia 20 de agosto tornou o mecanismo de skills pronto para produção, mas não tornou as opções desta tabela intercambiáveis.

Leitura relacionada: preços da Claude API por modelo e token e como gravar uma skill do Claude no Claude Code.