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

# Skill CNPJ

> Teach your AI coding agent to query Brazilian company data with a single command

The official **Agent Skill** from cnpj-api.com for AI coding agents (Claude Code, Cursor, Codex, Windsurf, OpenCode, and 40+ others). Installs a knowledge pack your agent already knows how to use: authentication, endpoints, error handling, and CNPJ formatting are all pre-configured.

<Frame>
  <img src="https://mintcdn.com/cnpj-api/EtnpaZNB1KGEaYtW/images/skill-cnpj/install-flow.svg?fit=max&auto=format&n=EtnpaZNB1KGEaYtW&q=85&s=9dc85c42751ef81c209ac5192ff6d53a" alt="One-command install and the agent using the skill" width="960" height="260" data-path="images/skill-cnpj/install-flow.svg" />
</Frame>

## Quick install

For most agents (Claude Code, Cursor, Codex, Windsurf, etc.), run in your project directory:

```bash theme={null}
npx skills add cnpj-api/skills
```

The CLI places the files in the right folder for your agent (`.claude/skills/`, `.cursor/skills/`, etc.) automatically.

<Note>
  Using **Claude.ai on the web or desktop**? The web app can't run `npx`. Follow the
  [Install on Claude manually](/en/skill-cnpj-claude-manual) guide to upload the ZIP directly.
</Note>

## Setup

1. Create a free account at [cnpj-api.com](https://cnpj-api.com) and generate a token.
2. Export the token as an environment variable:

```bash theme={null}
export CNPJ_API_TOKEN="your-token-here"
```

The agent reads this variable whenever the skill runs. It never stores or logs the value.

## What's included

Full cnpj-api coverage via 8 endpoints:

| Endpoint                    | Plan    | Description                        |
| --------------------------- | ------- | ---------------------------------- |
| `GET /v1/cnpj/{cnpj}`       | free+   | Full company profile               |
| `POST /v1/bulk-cnpj`        | **pro** | Batch lookup (up to 20)            |
| `GET /v1/simples/{cnpj}`    | free+   | Simples Nacional and SIMEI status  |
| `GET /v1/socios/{pessoaId}` | free+   | Partner profile and companies      |
| `GET /v1/cidades/{id}`      | free+   | IBGE city aggregates               |
| `GET /v1/cnae/{cnae}`       | free+   | Industry classification aggregates |
| `GET /v1/usage`             | free+   | Current plan and rate limit        |

Plus helper scripts (`validate-cnpj.ts` and `bulk-lookup.ts`).

## How to use it

After install, ask your agent in natural language:

<CardGroup cols={2}>
  <Card title="Single lookup" icon="magnifying-glass">
    *"Look up CNPJ 82.845.322/0001-04"*
  </Card>

  <Card title="Simples Nacional" icon="shield-check">
    *"Is this company in Simples Nacional?"*
  </Card>

  <Card title="Partners" icon="users">
    *"Show me the partners of this company"*
  </Card>

  <Card title="Bulk enrichment" icon="layer-group">
    *"Enrich this list of 50 CNPJs"*
  </Card>
</CardGroup>

The agent picks the right endpoint, handles errors, respects rate limits, and adds the `api-token` header automatically.

## Compatibility

Works with any agent that supports the [Agent Skills](https://agentskills.io) format:

<CardGroup cols={4}>
  <Card title="Claude Code" />

  <Card title="Cursor" />

  <Card title="Codex" />

  <Card title="Windsurf" />

  <Card title="OpenCode" />

  <Card title="Amp" />

  <Card title="Antigravity" />

  <Card title="+35 more" />
</CardGroup>

## Limits and plans

See plans and pricing at [cnpj-api.com/precos](https://cnpj-api.com/precos). Batch lookup (`/v1/bulk-cnpj`) requires the **Pro** plan.

## Open source

The skill is **MIT-licensed** and public:

* **Repository:** [github.com/cnpj-api/skills](https://github.com/cnpj-api/skills)
* **Agent Skills spec:** [agentskills.io](https://agentskills.io)

Issues and PRs welcome.

## Next steps

<CardGroup cols={2}>
  <Card title="Install on Claude manually" icon="upload" href="/en/skill-cnpj-claude-manual">
    Step-by-step guide for Claude.ai (web and desktop) with ZIP upload.
  </Card>

  <Card title="GitHub repository" icon="github" href="https://github.com/cnpj-api/skills">
    View the skill source, SKILL.md, references, and scripts.
  </Card>
</CardGroup>