> ## 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.

# Install on Claude manually

> How to upload the Skill CNPJ on Claude.ai (web and desktop) via ZIP

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

If you use **Claude.ai on the web** or the **Claude desktop app**, the `npx skills add` command isn't enough. Claude needs the skill uploaded through its UI. This guide walks through the full flow: enabling capabilities, uploading the ZIP, and allowlisting the API domain.

<Note>
  This guide is for Claude.ai. If you use Claude Code, Cursor, Codex, Windsurf, or any CLI
  that supports Agent Skills, use `npx skills add cnpj-api/skills` ([see here](/en/skill-cnpj)).
</Note>

## Prerequisites

* A Claude account (Free, Pro, or Max, works on all individual plans)
* A cnpj-api token ([create one for free](https://cnpj-api.com/sign-up))

## Step-by-step

<Steps>
  <Step title="Enable code execution">
    The skill makes HTTP calls to our API, so Claude needs "Code execution" enabled.

    1. Open **[claude.ai/settings/capabilities](https://claude.ai/settings/capabilities)**
    2. Turn on **Code execution and file creation**

    <Tip>
      On Team/Enterprise plans, the feature must be enabled by an owner under
      **Organization settings > Skills**.
    </Tip>
  </Step>

  <Step title="Download the skill ZIP">
    1. Open the repo: [github.com/cnpj-api/skills](https://github.com/cnpj-api/skills)
    2. Click the [Download skill.zip](https://github.com/cnpj-api/skills/releases/latest/download/skill.zip) button
  </Step>

  <Step title="Upload to Claude">
    1. Open **[claude.ai](https://claude.ai)** and go to **Customize → Skills** (on desktop,
       click the settings icon → Customize)
    2. Click **+ Create skill**
    3. Select **Upload a skill**
    4. Drag in `cnpj-api.zip` (or click to choose the file)
    5. Confirm. The skill appears in your custom skills list
  </Step>

  <Step title="Allowlist the API domain">
    The skill calls `https://api.cnpj-api.com`. By default, Claude only allows package
    managers, so you need to add the domain to the allowlist.

    1. Go back to **[claude.ai/settings/capabilities](https://claude.ai/settings/capabilities)**
    2. Find the **Domain allowlist** section (inside "Code execution and file creation")
    3. In **Additional allowed domains**, paste:

    ```
    api.cnpj-api.com
    ```

    4. Click **Add**

    <Warning>
      Without this step, Claude blocks the requests with `403 blocked-by-allowlist`.
    </Warning>
  </Step>

  <Step title="Provide the token">
    The agent reads `CNPJ_API_TOKEN` from the runtime environment. In Claude, paste the
    token in the first message of your chat (or configure it in the project's system prompt):

    ```
    Use this token for cnpj-api: CNPJ_API_TOKEN=your-token-here
    ```

    <Tip>
      Never share your token in public chats or screenshots. If it leaks, revoke it and
      generate a new one from [My Account](https://cnpj-api.com/my-account).
    </Tip>
  </Step>

  <Step title="Test the skill">
    In a new Claude chat, ask:

    > *"Look up CNPJ 82.845.322/0001-04"*

    Claude should detect the skill, call `/v1/cnpj/82845322000104` with the `api-token`
    header, and return data for **"SOFTPLAN PLANEJAMENTO E SISTEMAS S/A"**

    Other quick tests:

    * *"Is this company in Simples Nacional?"* → uses `/v1/simples/{cnpj}`
    * *"Show me the partners of this company"* → uses `/v1/socios/{pessoaId}`
    * *"Check my current plan"* → uses `/v1/usage`
  </Step>
</Steps>

## Common issues

<AccordionGroup>
  <Accordion title="Error: 'ZIP file is invalid'">
    The `cnpj-api/` folder must be at the root of the ZIP. If you zipped the whole
    repository, extract it, go into `skills-main/skills/`, and re-zip just `cnpj-api/` from there.
  </Accordion>

  <Accordion title="Error: '403 blocked-by-allowlist'">
    You skipped Step 4: adding `api.cnpj-api.com` to
    **Capabilities → Domain allowlist**. Without it, Claude blocks every HTTP request.
  </Accordion>

  <Accordion title="Error: '401 TOKEN_MISSING'">
    The agent never received `CNPJ_API_TOKEN`. Paste the token in the first chat message
    or add it to the project's system prompt.
  </Accordion>

  <Accordion title="The skill doesn't appear in the list">
    Refresh [claude.ai/settings/capabilities](https://claude.ai/settings/capabilities).
    If it still doesn't show, verify that **Code execution and file creation** is enabled.
  </Accordion>

  <Accordion title="Claude doesn't activate the skill automatically">
    Mention the context explicitly: *"Look up CNPJ X"*, *"company data..."*,
    *"Simples Nacional"*. Claude uses the `description` field in `SKILL.md` to decide.
  </Accordion>
</AccordionGroup>

## References

* **Skills in Claude (official):** [support.claude.com · Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
* **Creating custom skills:** [support.claude.com · How to create custom skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills)
* **Agent Skills specification:** [agentskills.io/specification](https://agentskills.io/specification)
* **Skill CNPJ repository:** [github.com/cnpj-api/skills](https://github.com/cnpj-api/skills)