> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnpj-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalar no Claude manualmente

> Como fazer o upload da Skill CNPJ no Claude.ai (web e desktop) via ZIP

<Frame>
  <iframe width="100%" height="400" src="https://www.youtube.com/embed/pjFndppx9rU" title="Instalar Skill CNPJ no Claude.ai" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />
</Frame>

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.

<Note>
  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](/pt/skill-cnpj)).
</Note>

## Pré-requisitos

* Conta Claude (Free, Pro ou Max, funciona em todos os planos individuais)
* Token da cnpj-api ([crie grátis aqui](https://cnpj-api.com/sign-up))

## Passo a passo

<Steps>
  <Step title="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](https://claude.ai/settings/capabilities)**
    2. Ative **Execução de código e criação de arquivos**

    <Tip>
      Em planos Team/Enterprise o recurso precisa ser habilitado em **Organization settings > Skills**
      pelo owner da organização.
    </Tip>
  </Step>

  <Step title="Baixe o ZIP da skill">
    1. Abra o repositório: [github.com/cnpj-api/skills](https://github.com/cnpj-api/skills)
    2. Clique no botão [Download skill.zip](https://github.com/cnpj-api/skills/releases/latest/download/skill.zip)
  </Step>

  <Step title="Faça o upload no Claude">
    1. Abra **[claude.ai](https://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
  </Step>

  <Step title="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](https://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
    ```

    4. Clique em **Add**

    <Warning>
      Sem essa etapa, o Claude bloqueia as requisições com `403 blocked-by-allowlist`.
    </Warning>
  </Step>

  <Step title="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
    ```

    <Tip>
      Nunca compartilhe seu token em chats públicos ou prints. Se vazar, revogue e gere um
      novo em [Minha Conta](https://cnpj-api.com/my-account).
    </Tip>
  </Step>

  <Step title="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`
  </Step>
</Steps>

## Problemas comuns

<AccordionGroup>
  <Accordion title="Erro: 'ZIP file is invalid'">
    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á.
  </Accordion>

  <Accordion title="Erro: '403 blocked-by-allowlist'">
    Você esqueceu o Passo 4: adicionar `api.cnpj-api.com` em
    **Capabilities → Domain allowlist**. Sem isso o Claude bloqueia toda requisição HTTP.
  </Accordion>

  <Accordion title="Erro: '401 TOKEN_MISSING'">
    O agente não recebeu `CNPJ_API_TOKEN`. Cole o token na primeira mensagem do chat ou
    configure no system prompt do projeto.
  </Accordion>

  <Accordion title="A skill não aparece na lista">
    Faça refresh em [claude.ai/settings/capabilities](https://claude.ai/settings/capabilities).
    Se ainda não aparecer, verifique se **Code execution and file creation** está habilitado.
  </Accordion>

  <Accordion title="A Claude não ativa a skill automaticamente">
    Mencione o contexto claramente: *"Consulte o CNPJ X"*, \*"dados da empresa...",
    *"Simples Nacional"*. A Claude usa o campo `description` do `SKILL.md` para decidir.
  </Accordion>
</AccordionGroup>

## Referências

* **Skills no Claude (doc oficial):** [support.claude.com · Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
* **Criar skills customizadas:** [support.claude.com · How to create custom skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills)
* **Especificação Agent Skills:** [agentskills.io/specification](https://agentskills.io/specification)
* **Repositório da Skill CNPJ:** [github.com/cnpj-api/skills](https://github.com/cnpj-api/skills)