Pular para o conteúdo principal
Se você usa o Claude.ai na web ou o app desktop do Claude, o comando npx skills add não é suficiente. O Claude precisa que a skill seja enviada via interface. Este guia cobre todo o fluxo: habilitar capacidades, fazer o upload do ZIP e liberar o domínio da API.
Este guia é para o Claude.ai. Se você usa Claude Code, Cursor, Codex, Windsurf ou qualquer CLI que suporte Agent Skills, use npx skills add cnpj-api/skills (instruções aqui).

​
Pré-requisitos

  • Conta Claude (Free, Pro ou Max, funciona em todos os planos individuais)
  • Token da cnpj-api (crie grátis aqui)

​
Passo a passo

1

Habilite execução de código

A skill faz chamadas HTTP para a nossa API, então o Claude precisa de “Code execution” habilitado.
  1. Abra claude.ai/settings/capabilities
  2. Ative Execução de código e criação de arquivos
Em planos Team/Enterprise o recurso precisa ser habilitado em Organization settings > Skills pelo owner da organização.
2

Baixe o ZIP da skill

  1. Abra o repositório: github.com/cnpj-api/skills
  2. Clique no botão Download skill.zip
3

Faça o upload no Claude

  1. Abra claude.ai e vá em Customize → Skills (no desktop, é o ícone de ajustes → Customize)
  2. Clique no botão + Create skill
  3. Selecione Upload a skill
  4. Arraste o arquivo cnpj-api.zip (ou clique para selecionar)
  5. Confirme. A skill aparece na sua lista de skills customizadas
4

Libere o domínio da API

A skill chama https://api.cnpj-api.com. Por padrão o Claude só libera package managers, então você precisa adicionar o domínio na allowlist.
  1. Volte em claude.ai/settings/capabilities
  2. Localize a seção Domain allowlist (dentro de “Code execution and file creation”)
  3. Em Additional allowed domains, cole:
api.cnpj-api.com
  1. Clique em Add
Sem essa etapa, o Claude bloqueia as requisições com 403 blocked-by-allowlist.
5

Configure o token

O agente lê CNPJ_API_TOKEN do ambiente de execução. No Claude, exporte a variável assim na primeira mensagem do chat (ou configure no system prompt se preferir):
Use este token para a cnpj-api: CNPJ_API_TOKEN=seu-token-aqui
Nunca compartilhe seu token em chats públicos ou prints. Se vazar, revogue e gere um novo em Minha Conta.
6

Teste a skill

Em um novo chat com o Claude, peça:
“Consulte o CNPJ 82.845.322/0001-04”
A Claude deve detectar a skill, chamar /v1/cnpj/82845322000104 com o header api-token e retornar os dados da “SOFTPLAN PLANEJAMENTO E SISTEMAS S/A”.Outros testes rápidos:
  • “Essa empresa é Simples Nacional?” → usa /v1/simples/{cnpj}
  • “Me dá os sócios dessa empresa” → usa /v1/socios/{pessoaId}
  • “Consulte meu plano atual” → usa /v1/usage

​
Problemas comuns

A pasta cnpj-api/ precisa estar na raiz do ZIP. Se você compactou o repositório inteiro, extraia, entre em skills-main/skills/ e compacte só cnpj-api/ lá.
Você esqueceu o Passo 4: adicionar api.cnpj-api.com em Capabilities → Domain allowlist. Sem isso o Claude bloqueia toda requisição HTTP.
O agente não recebeu CNPJ_API_TOKEN. Cole o token na primeira mensagem do chat ou configure no system prompt do projeto.
Faça refresh em claude.ai/settings/capabilities. Se ainda não aparecer, verifique se Code execution and file creation está habilitado.
Mencione o contexto claramente: “Consulte o CNPJ X”, *“dados da empresa…”, “Simples Nacional”. A Claude usa o campo description do SKILL.md para decidir.

​
Referências