Skill Claude API

A skill claude-api é uma Agent Skill de código aberto que fornece ao Claude material de referência detalhado e atualizado para criar aplicações em duas superfícies da Anthropic:

• Messages API: A superfície principal para requisições únicas, chat com streaming, "tool use" (uso de ferramentas), "batch processing" (processamento em lote), "prompt caching" (cache de prompt), "structured outputs" (saídas estruturadas) e "agent loops" (loops de agente) personalizados.
• Claude Managed Agents (beta): Uma superfície hospedada pela Anthropic para agentes com estado gerenciados pelo servidor, com execução de ferramentas hospedada pela Anthropic, configurações de agente persistentes e sandboxes por sessão.

Ela abrange oito linguagens de programação, tanto para a Messages API quanto para o Managed Agents: Python, TypeScript, C#, Go, Java, PHP, Ruby e cURL.

A skill vem incluída no Claude Code e também está disponível no repositório de skills da Anthropic, de código aberto, onde você pode instalá-la em qualquer ambiente que ofereça suporte a Agent Skills.

A skill usa "progressive disclosure" (divulgação progressiva) para manter o contexto eficiente: o Claude carrega apenas a documentação relevante para a linguagem do seu projeto, a superfície (Messages API ou Managed Agents) e a tarefa específica em questão (uso de ferramentas, streaming, lotes e assim por diante), em vez de carregar tudo de uma vez.

O que a skill oferece

Quando acionada, a skill equipa o Claude com:

Para a Messages API:

• Documentação de SDK específica por linguagem: Instalação, início rápido, padrões comuns e tratamento de erros para a linguagem do seu projeto
• Orientações sobre uso de ferramentas: Exemplos específicos por linguagem e fundamentos conceituais para chamada de funções, incluindo o tool runner beta, quando disponível
• Padrões de streaming: Detalhes de implementação para criar interfaces de chat e lidar com exibição incremental
• Processamento em lote: Processamento em lote offline com 50% do custo
• Cache de prompt: Design com estabilidade de prefixo, posicionamento de breakpoints e auditoria de invalidadores silenciosos
• Migração de modelo: Orientação passo a passo para migrar para modelos Claude mais recentes (incluindo as mudanças incompatíveis e alterações de comportamento no Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5 e no Claude Fable 5.1)
• Migração para pensamento preservado: Encontrar, medir e corrigir as edições de histórico que invalidam blocos thinking, disponível por meio do subcomando /claude-api preserved-thinking-migration
• Informações atuais sobre modelos: IDs de modelos, tamanhos da "context window" (janela de contexto) e preços
• Armadilhas comuns: Orientações detalhadas para evitar erros frequentes ao integrar com a API

Para o Managed Agents (beta):

• Fluxo de onboarding: Um passo a passo guiado por entrevista para configurar um novo Managed Agent do zero, disponível por meio do subcomando /claude-api managed-agents-onboard
• Documentação do Managed Agents específica da linguagem: Criação de agentes persistentes, início de sessões, streaming de eventos e tratamento de confirmações de ferramentas para Python, TypeScript, C#, Go, Java, PHP, Ruby e cURL
• Padrões de cliente: Reconexão de stream sem perdas, controle de enfileirado/processado via processed_at, tratamento de interrupções, armadilhas na montagem de arquivos e tratamento de credenciais
• Restrições de implantação: O Managed Agents está disponível apenas na Claude API e na Claude Platform on AWS (não no Amazon Bedrock, no Google Cloud nem no Microsoft Foundry). Para outras implantações, a skill direciona para a Messages API e o uso de ferramentas.

Quando a skill é ativada

A skill é ativada de duas formas:

A ativação automática ocorre quando:

• Seu código importa um SDK da Anthropic (anthropic para Python, @anthropic-ai/sdk para TypeScript/JavaScript)
• Você pede ao Claude ajuda para criar, depurar ou otimizar algo com a Claude API, um SDK da Anthropic ou o Managed Agents
• Você adiciona, modifica ou ajusta um recurso do Claude em um arquivo (cache de prompt, adaptive thinking, compaction, uso de ferramentas, batch, files, citations, memory) ou uma referência de modelo

A invocação manual é feita digitando /claude-api (com um subcomando ou texto opcional) em qualquer ambiente onde a skill esteja instalada.

A skill não é ativada para tarefas gerais de programação, trabalhos de ML/ciência de dados ou código que importa outros SDKs de IA (como o da OpenAI).

Linguagens suportadas

A skill detecta automaticamente a linguagem do seu projeto examinando os arquivos do projeto (por exemplo, requirements.txt para Python, tsconfig.json para TypeScript, go.mod para Go) e carrega a documentação apropriada.

Se o seu projeto usa várias linguagens, o Claude pergunta qual delas se aplica. Para linguagens não suportadas (Rust, Swift, C++), a skill fornece exemplos em cURL/HTTP puro.

Como usar a skill

No Claude Code (incluída)

A skill vem com o Claude Code e não requer instalação. Quando você pede ao Claude ajuda para criar algo com a Claude API, ou quando seu projeto já importa um SDK da Anthropic, a skill é ativada automaticamente.

Você também pode invocá-la diretamente:

Para saber mais sobre como as skills incluídas funcionam no Claude Code, consulte a documentação de skills do Claude Code.

A partir do repositório de skills

O código-fonte da skill está disponível no repositório de skills da Anthropic. Você pode instalá-la usando o comando npx:

npx skills add https://github.com/anthropics/skills --skill claude-api

Ou peça ao Claude Code para instalá-la como um plugin do Claude Code:

/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills

Migrando para um modelo Claude mais recente

A skill Claude API pode realizar migrações de modelos Claude em toda uma base de código. Invoque-a diretamente com /claude-api migrate:

Você também pode informar um escopo específico logo de início para pular a pergunta de confirmação de escopo:

Quando o escopo é ambíguo (por exemplo, um simples /claude-api migrate to claude-opus-5-5), a skill pede que você escolha entre todo o diretório de trabalho, um subdiretório específico ou uma lista explícita de arquivos antes de editar qualquer arquivo. Isso se aplica tanto a chamadores da Messages API quanto do Managed Agents.

A skill lida com:

• Troca de IDs de modelo, incluindo constantes tipadas dos SDKs (Model.CLAUDE_OPUS_4_8 → Model.CLAUDE_OPUS_5_5) em todas as linguagens suportadas, e classifica cada arquivo como chamador, definidor de modelo ou referência de string opaca antes de editar
• Detecção de plataforma de nuvem, preservando formatos de ID de modelo específicos de cada plataforma (por exemplo, o prefixo anthropic. no Amazon Bedrock) e ignorando alterações para recursos indisponíveis em plataformas operadas por parceiros
• Mudanças incompatíveis de parâmetros, como a remoção de temperature, top_p e top_k para o Claude Opus 4.8 e o Claude Opus 4.7, e a conversão de thinking: {type: "enabled", budget_tokens: N} para thinking: {type: "adaptive"}
• Substituição de prefill, convertendo padrões de prefill de mensagens do assistente em saídas estruturadas, quando aplicável
• Limpeza de cabeçalhos beta, removendo cabeçalhos beta que o modelo de destino não exige (por exemplo, effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14) e voltando de client.beta.messages.create() para client.messages.create()
• Calibração de esforço, recomendando um ponto de partida de output_config.effort para o modelo de destino (por exemplo, o padrão high no Claude Opus 5, e xhigh para casos de uso de programação e agênticos no Claude Opus 4.8 e no Claude Opus 4.7)
• Ajuste de comportamento de prompts, sinalizando prompts de controle de tamanho, acionamento de ferramentas, subagentes e seguimento de instruções que podem se comportar de forma diferente no modelo de destino
• Tratamento de padrões silenciosos, reativando a sumarização do pensamento (thinking.display: "summarized") quando o raciocínio é exibido aos usuários no Claude Opus 4.8 e no Claude Opus 4.7
• Configuração de fallback para recusas, adicionando o tratamento de stop_reason: "refusal" antes de ler o conteúdo da resposta e configurando um caminho de nova tentativa com fallback quando o destino é o Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5 ou Claude Sonnet 5.5 (o parâmetro fallbacks do lado do servidor, normalmente em seu modo "default", o middleware de fallback para recusas do SDK ou uma nova tentativa com crédito de fallback), e atualizando código de fallback escrito com base em formatos de prévia anteriores

À medida que edita, a skill explica cada alteração e sua motivação diretamente no código. Ao concluir, ela produz uma checklist de itens que exigem verificação manual (normalmente testes de integração, ajuste de prompts de controle de tamanho e redefinição da linha de base de custo/limite de taxa).

Para a lista completa de alterações específicas de modelo que a skill aplica, consulte Migrando para o Claude Opus 5.5 a partir do Claude Opus 5, Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.8, Migrando para o Claude Sonnet 5.5 a partir do Claude Sonnet 5, guia de migração para o Claude Haiku 5.5 e guia de migração para o Claude Fable 5.1 e o Claude Mythos 5.1.

Verificando uma integração para pensamento preservado

O "preserved thinking" (pensamento preservado) mantém um bloco thinking válido apenas enquanto o prompt system, as tools e as mensagens anteriores a ele permanecem inalterados. Para encontrar e corrigir os pontos em que seu código edita esse histórico, abra o repositório que constrói suas requisições e invoque o subcomando preserved-thinking-migration:

A skill trabalha em cinco etapas:

1. Escopo: Verifica se sua integração é afetada e, em seguida, envia três requisições de teste para confirmar que a API reporta uma edição deliberada.
2. Encontrar: Captura algumas de suas próprias sessões de múltiplos turnos, compara requisições consecutivas e lista cada ponto em que seu código edita o prefixo.
3. Medir: Reproduz as sessões com "drop_block" e informa quais conversas perdem blocos thinking, em qual turno e por quê.
4. Corrigir: Substitui uma edição por vez pelo padrão correspondente em Fazer mudanças sem editar o prefixo e mede novamente após cada alteração.
5. Relatar: Resume cada causa, a alteração feita para ela e as contagens antes e depois.

Se o seu projeto tiver uma avaliação (eval), a skill também compara pontuações e uso de tokens com e sem blocos thinking descartados.

As requisições de teste e as reproduções são requisições reais à Messages API, cobradas pelas tarifas normais do modelo. Cada reprodução solicita apenas alguns tokens de saída e define tool_choice como none, de modo que nenhuma ferramenta é executada. A skill informa o custo e pede sua aprovação antes de enviá-las.

Configurando um Managed Agent

Para criar a estrutura de um novo Managed Agent do zero, invoque o subcomando managed-agents-onboard:

A skill conduz uma entrevista que apresenta o modelo mental do Managed Agents (configurações de Agent versus Sessions), cria um modelo de configuração de agente, configura ambientes e ferramentas, configura o loop de sessão e gera código executável para a sua linguagem. A skill também aborda o fluxo obrigatório Agent (uma vez) → Session (a cada execução): model, system e tools ficam no agente, nunca na sessão, e os agentes devem ser criados uma única vez e referenciados por ID.

O Managed Agents requer o cabeçalho beta managed-agents-2026-04-01, que o SDK define automaticamente para todas as chamadas client.beta.agents.*, client.beta.environments.*, client.beta.sessions.* e client.beta.vaults.*.

Exemplos de uso

Aqui estão exemplos de tarefas com as quais a skill ajuda o Claude:

Criando uma aplicação de chat:

Migrando um projeto existente:

Fazendo o onboarding de um novo Managed Agent:

Em cada caso, a skill carrega a documentação relevante específica da linguagem e orienta o Claude durante a implementação usando os padrões atuais da API e as boas práticas.

Próximos passos