Como usar o Claude Code com qualquer modelo: a configuração do SKILL.md

Claude Code pode se tornar muito mais útil quando sabe como funciona a sua camada de roteamento de IA. A configuração do SKILL.md é a forma limpa de ensiná-lo a esse fluxo de trabalho: onde fica o roteador da Flatkey, como descobrir IDs de modelos em tempo real, como chamar modelos e ferramentas suportados e quais regras de segurança seguir antes de gastar saldo ou tocar em sistemas de produção.

Há uma ressalva importante logo de início. O próprio ciclo de raciocínio do Claude Code ainda roda no Claude. A documentação do gateway da Anthropic diz que o Claude Code pode se conectar a um gateway de LLM, mas não oferece suporte para rotear o próprio Claude Code para modelos que não sejam Claude por meio de um gateway. Use este guia para a versão prática de Como usar o Claude Code com qualquer modelo: a configuração do SKILL.md: mantenha o Claude Code como seu agente de codificação e, em seguida, dê a ele uma skill da Flatkey para que ele possa descobrir e chamar qualquer modelo ou ferramenta com medição suportados pela Flatkey no seu projeto, quando a tarefa exigir isso.

O SKILL.md público da Flatkey foi criado para essa tarefa. Ele orienta os agentes a usar https://router.flatkey.ai, a URL base compatível com OpenAI https://router.flatkey.ai/v1, o catálogo de modelos em tempo real, o marketplace de ferramentas, chamadas iniciais pequenas, IDs de solicitação e gates de aprovação para gravações, envios, compras, exclusões, publicação ou alterações de permissão.

Se você é novo no roteador em si, mantenha o guia rápido da API da Flatkey aberto ao lado deste guia. Se estiver comparando isso com uma migração mais ampla de provedor, os guias alternativa à API da OpenAI e fluxo de trabalho de API unificada de IA explicam o padrão da URL base com mais detalhes.

A resposta rápida

Use esta configuração quando quiser que o Claude Code opere a Flatkey de dentro do seu repositório:

1. Crie uma chave de API da Flatkey no Console da Flatkey.
2. Instale a skill da Flatkey no Claude Code como ~/.claude/skills/flatkey/SKILL.md ou .claude/skills/flatkey/SKILL.md.
3. Armazene FLATKEY_API_KEY no seu shell ou gerenciador local de segredos, não em um arquivo commitado.
4. Peça ao Claude Code para usar a skill da Flatkey, buscar o catálogo de modelos em tempo real e executar uma pequena chamada de teste por meio de https://router.flatkey.ai/v1.
5. Verifique os Logs de Uso da Flatkey para modelo, contagem de tokens, latência, status e custo.

Se você quiser que o tráfego da família Claude do Claude Code passe pela Flatkey, use o guia do Claude Code da Flatkey em vez da URL base /v1 compatível com OpenAI:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Esse caminho é para roteamento de gateway do Claude Code. O caminho do SKILL.md é para ensinar o Claude Code a usar os modelos e ferramentas da Flatkey a partir do projeto.

O que o SKILL.md muda no Claude Code

Uma skill do Claude Code é um diretório com um arquivo SKILL.md. O Claude Code carrega os metadados da skill na inicialização e depois lê o conteúdo da skill somente quando a tarefa corresponde ou quando você invoca a skill diretamente. Isso faz de uma skill um local melhor do que CLAUDE.md para procedimentos repetíveis como "descobrir modelos da Flatkey, selecionar uma rota suportada, executar uma chamada pequena e verificar os Logs de Uso".

Com o Flatkey, a skill deve fazer com que o Claude Code faça cinco coisas de forma consistente:

Esse é o núcleo prático de Como usar o Claude Code com qualquer modelo: a configuração do SKILL.md. O Claude Code continua sendo o orquestrador. O Flatkey se torna a camada de modelo e ferramenta com a qual ele pode operar de forma deliberada.

Etapa 1: Escolha a instalação pessoal ou de projeto

Instale a skill globalmente se quiser que ela esteja disponível em todos os repositórios:

mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

Instale-a dentro de um repositório se quiser que a equipe compartilhe o mesmo fluxo de trabalho do Flatkey:

mkdir -p .claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o .claude/skills/flatkey/SKILL.md

Para uma skill de projeto compartilhada, revise o arquivo antes de fazer commit:

sed -n '1,200p' .claude/skills/flatkey/SKILL.md

Não transforme o comando de instalação em um script de shell executado automaticamente. Uma skill é conteúdo de instruções. Trate-a como adicionar qualquer outro procedimento de desenvolvimento ao seu repositório: busque-a, revise-a e faça commit dela apenas se a equipe concordar.

Etapa 2: Defina a chave do Flatkey com segurança

Use uma variável de ambiente:

export FLATKEY_API_KEY="sk-fk-your-key"

Se precisar que a variável persista, coloque-a no perfil do seu shell, no seu gerenciador de segredos ou em um arquivo de ambiente local que seja ignorado pelo git. Não coloque a chave em .claude/settings.json, CLAUDE.md, um SKILL.md commitado ou em um prompt que você cole em uma thread compartilhada.

A própria regra da skill do Flatkey é simples: use um FLATKEY_API_KEY existente quando já houver um configurado e nunca imprima, registre, faça commit ou envie essa chave para qualquer lugar exceto router.flatkey.ai ou o Console autenticado do Flatkey.

Etapa 3: Confirme que o Claude Code vê a skill

Inicie o Claude Code a partir do repositório ou do terminal onde a skill está disponível:

claude

Em seguida, verifique as skills disponíveis:

/skills

Você deve ver flatkey na lista de skills. Se você instalou a skill durante uma sessão do Claude Code em execução e ela não aparecer, reinicie o Claude Code. O Claude Code pode detectar muitas edições de skills durante uma sessão, mas reiniciar é a forma mais simples de remover ambiguidades durante a configuração.

Agora peça uma primeira tarefa inofensiva:

Use a skill flatkey. Verifique se FLATKEY_API_KEY está disponível sem exibi-la, busque o catálogo de modelos ao vivo da Flatkey e resuma os primeiros cinco IDs de modelos capazes de texto que você encontrar. Não execute uma geração ainda.

Isso testa a descoberta sem gastar orçamento de geração.

Passo 4: Busque o catálogo de modelos ao vivo

A skill Flatkey diz ao Claude Code para buscar o catálogo de modelos ao vivo antes de selecionar um modelo. O comando direto é:

curl -fsS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Para um fluxo de trabalho real, peça ao Claude Code para escolher apenas entre os IDs retornados:

Use a skill flatkey. Busque o catálogo de modelos ao vivo, escolha um modelo de texto de baixo custo retornado pelo catálogo para um teste rápido de uma frase e explique por que você o escolheu antes de executar a solicitação.

Isso evita um erro comum de agente: usar um nome de modelo da memória ou de um artigo antigo. O catálogo é a fonte da verdade sobre o que sua chave pode chamar naquele momento.

Passo 5: Execute uma pequena chamada de validação compatível com OpenAI

Assim que o catálogo retornar, execute uma pequena solicitação pela API compatível com OpenAI da Flatkey:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "substitua-por-um-id-de-modelo-do-catálogo-ao-vivo",
    "messages": [
      {
        "role": "user",
        "content": "Responda com uma frase: teste de validação da Flatkey aprovado."
      }
    ],
    "max_tokens": 40
  }'

Mantenha a primeira chamada simples. Você está testando autenticação, ID do modelo, URL base, formato da resposta e visibilidade do ledger. Guarde prompts de longo contexto, chamadas de ferramenta, geração de imagens e jobs em lote até que o caminho básico funcione.

Passo 6: Deixe o Claude Code chamar qualquer modelo compatível a partir de uma tarefa

Depois que o teste de validação passar, você pode pedir ao Claude Code para direcionar o trabalho a um modelo que se adeque à tarefa.

Por exemplo:

Use a skill flatkey. Preciso de uma revisão por um segundo modelo desta função. Busque o catálogo ao vivo, selecione um modelo capaz de codificação retornado pelo catálogo, execute uma pequena solicitação de revisão pela Flatkey e informe o ID do modelo, o resultado da solicitação e quaisquer campos de request ID ou usage retornados. Não exiba segredos.

Ou:

Use a skill flatkey. Compare dois modelos de texto compatíveis com a Flatkey neste prompt. Mantenha ambas as chamadas abaixo de 200 tokens de saída. Mostre as saídas lado a lado e diga qual deles devo usar para esta tarefa de sumarização interna de baixo risco.

Esse é o padrão de "qualquer modelo" que funciona bem com o Claude Code: o Claude Code coordena a tarefa, lê arquivos, aplica o contexto do repositório e usa o Flatkey como um caminho externo controlado para o modelo quando um segundo modelo ou uma família de modelos diferente é útil.

Para a escolha de modelo em produção, combine isso com o guia de catálogo de modelos de IA para que o Claude Code revise o tipo de endpoint, o preço por unidade, a disponibilidade e o status de verificação antes de recomendar uma rota.

Etapa 7: Use as ferramentas do Flatkey somente após a inspeção

O SKILL.md do Flatkey também cobre ferramentas com medição de uso. A regra importante é que o Claude Code deve inspecionar uma ferramenta antes de executá-la. Ele não deve inventar IDs de ferramentas, campos obrigatórios, preços, nomes de provedores ou unidades de cobrança.

Um bom primeiro prompt é:

Use a skill do flatkey. Abra o marketplace de ferramentas do Flatkey no navegador, inspecione as ferramentas relacionadas a busca disponíveis para a minha conta e resuma os campos obrigatórios e a unidade de cobrança de uma ferramenta candidata. Não execute a ferramenta ainda.

Depois, quando você estiver pronto:

Use a skill do flatkey. Execute a ferramenta inspecionada com um limite pequeno e uma chave de idempotência. Antes da execução, repita exatamente a ferramenta, os campos obrigatórios, a unidade de cobrança esperada e o orçamento máximo para minha aprovação.

Isso mantém o Claude Code útil sem permitir que um agente derive para chamadas pagas descontroladas.

Etapa 8: Encaminhe o tráfego Claude do Claude Code pelo Flatkey quando necessário

A configuração do SKILL.md não é a mesma coisa que encaminhar o próprio Claude Code por meio de um gateway. Se o seu objetivo é executar as solicitações da família Claude do Claude Code pelo Flatkey, configure o Claude Code como um cliente de gateway no formato Anthropic:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Não use /v1 ao final para este caminho. O Claude Code e o SDK da Anthropic acrescentam a rota necessária. Depois de definir as variáveis, inicie o Claude Code no mesmo shell e execute:

/status

Procure a URL base da Anthropic e a origem da credencial. Em seguida, envie um prompt curto e verifique os logs de uso do Flatkey. Se a URL base não aparecer, o Claude Code não recebeu a variável de ambiente.

Use este caminho quando quiser que o uso do Claude no Claude Code apareça no saldo e no livro-razão do Flatkey. Use o caminho da skill quando quiser que o Claude Code chame modelos e ferramentas compatíveis com o Flatkey a partir do seu repositório.

Para decisões de roteamento relacionadas, veja roteamento de API Claude vs GPT. Se o seu caso de uso for um agente que chama ferramentas externas, a lista de verificação da API Gemini para agentes de IA é útil mesmo quando a família de modelos muda, porque os controles são semelhantes: IDs exatos de modelo, tentativas limitadas, validação de ferramentas e revisão de uso.

Erros comuns

Erro 1: assumir que o SKILL.md muda o cérebro do Claude Code

Não. Uma skill fornece ao Claude Code instruções e procedimentos reutilizáveis. Ela não transforma o loop de agente do próprio Claude Code em GPT, Gemini, DeepSeek, Qwen ou outro modelo.

Erro 2: Usar /v1 com ANTHROPIC_BASE_URL

O base URL compatível com OpenAI da Flatkey é:

https://router.flatkey.ai/v1

O roteamento do gateway do Claude Code usa:

https://router.flatkey.ai

Mantenha esses dois separados.

Erro 3: Fazer commit de credenciais nas configurações do Claude

O projeto .claude/settings.json normalmente é compartilhado com o repositório. Não coloque chaves nele. Use exports do shell, um cofre ou .claude/settings.local.json apenas se o seu repositório o ignorar e sua equipe aceitar esse fluxo local.

Erro 4: Deixar o agente adivinhar IDs de modelos

Sempre busque /v1/models primeiro. Se um ID de modelo não estiver na resposta do catálogo ao vivo para a sua chave, não o use.

Erro 5: Executar ferramentas pagas antes de inspecioná-las

Para as Flatkey Tools, inspecione primeiro os campos obrigatórios, exemplos, unidade de cobrança e preço exato. Depois, use uma chave de idempotência e peça aprovação antes da execução.

Uma lista de verificação de configuração copiável

Use esta lista para uma máquina de desenvolvimento:

# 1. Instale a skill da Flatkey para o Claude Code
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

# 2. Revise-a
sed -n '1,200p' ~/.claude/skills/flatkey/SKILL.md

# 3. Exporte sua chave da Flatkey
export FLATKEY_API_KEY="sk-fk-your-key"

# 4. Inicie o Claude Code
claude

Depois, solicite:

Use a skill da flatkey. Confirme que a skill da Flatkey foi carregada, verifique se FLATKEY_API_KEY está disponível sem imprimi-la, busque o catálogo de modelos ao vivo e execute um pequeno teste de fumaça de chat-completions por https://router.flatkey.ai/v1 usando um ID de modelo retornado pelo catálogo.

Após a chamada, abra os Flatkey Usage Logs e confirme que a solicitação aparece com o modelo esperado, status, contagens de tokens, latência e custo.

FAQ

O Claude Code pode usar qualquer modelo por meio do SKILL.md?

O Claude Code ainda executa com Claude. A configuração do SKILL.md permite que o Claude Code descubra e chame modelos e ferramentas compatíveis com a Flatkey a partir do seu projeto, de modo que uma tarefa possa usar outros modelos por meio da API da Flatkey quando apropriado.

Isso é o mesmo que mudar ANTHROPIC_BASE_URL?

Não. ANTHROPIC_BASE_URL=https://router.flatkey.ai roteia o tráfego da família Claude do Claude Code por meio de um gateway. Instalar https://flatkey.ai/SKILL.md ensina o Claude Code a operar as APIs e ferramentas da Flatkey durante uma tarefa.

Devo instalar a skill da Flatkey globalmente ou no repositório?

Use ~/.claude/skills/flatkey/ para uso pessoal entre projetos. Use .claude/skills/flatkey/ quando o repositório deva carregar um fluxo de trabalho compartilhado pela equipe. Faça commit apenas do arquivo de skill revisado, nunca de uma credencial.

Por que o guia busca /v1/models primeiro?

Porque a disponibilidade dos modelos muda. O catálogo ao vivo da Flatkey é mais seguro do que um nome de modelo copiado da memória, de uma resposta de chat ou de um documento antigo.

O que devo verificar após a configuração?

Verifique três coisas: se o Claude Code vê a skill, se a solicitação ao catálogo da Flatkey é bem-sucedida e se os Usage Logs mostram a solicitação de smoke com modelo, status, tokens, latência e custo.

Referências oficiais

• Flatkey SKILL.md: https://flatkey.ai/SKILL.md
• Flatkey quickstart: https://docs.flatkey.ai/quickstart.md
• Guia do Claude Code da Flatkey: https://docs.flatkey.ai/guides/claude-code.md
• Guia do SDK OpenAI da Flatkey: https://docs.flatkey.ai/guides/openai-sdk.md
• Skills do Claude Code da Anthropic: https://code.claude.com/docs/en/skills
• Documentação do gateway do Claude Code da Anthropic: https://docs.anthropic.com/en/docs/claude-code/llm-gateway.md
• Guia de conexão do gateway da Anthropic: https://docs.anthropic.com/en/docs/claude-code/llm-gateway-connect.md
• Visão geral do Agent Skills da Anthropic: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview