Skip to main content
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.
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).

​
Prerequisites

  • A Claude account (Free, Pro, or Max, works on all individual plans)
  • A cnpj-api token (create one for free)

​
Step-by-step

1

Enable code execution

The skill makes HTTP calls to our API, so Claude needs “Code execution” enabled.
  1. Open claude.ai/settings/capabilities
  2. Turn on Code execution and file creation
On Team/Enterprise plans, the feature must be enabled by an owner under Organization settings > Skills.
2

Download the skill ZIP

  1. Open the repo: github.com/cnpj-api/skills
  2. Click the Download skill.zip button
3

Upload to Claude

  1. Open 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
4

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
  2. Find the Domain allowlist section (inside “Code execution and file creation”)
  3. In Additional allowed domains, paste:
api.cnpj-api.com
  1. Click Add
Without this step, Claude blocks the requests with 403 blocked-by-allowlist.
5

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
Never share your token in public chats or screenshots. If it leaks, revoke it and generate a new one from My Account.
6

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

​
Common issues

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.
You skipped Step 4: adding api.cnpj-api.com to Capabilities → Domain allowlist. Without it, Claude blocks every HTTP request.
The agent never received CNPJ_API_TOKEN. Paste the token in the first chat message or add it to the project’s system prompt.
Refresh claude.ai/settings/capabilities. If it still doesn’t show, verify that Code execution and file creation is enabled.
Mention the context explicitly: “Look up CNPJ X”, “company data…”, “Simples Nacional”. Claude uses the description field in SKILL.md to decide.

​
References