Verificação de empresas polonesas como uma Skill do Claude

Se você usa o Claude Code ou os aplicativos Claude e já lidou com empresas polonesas, aqui está uma pequena coisa que economiza uma quantidade surpreendente de tempo: uma Skill que permite ao Claude verificar uma empresa pelo seu ID fiscal, checar se é um contribuinte de IVA registrado, procurar sua conta bancária na lista branca do governo, puxar seus dados do registro judicial e validar um número de IVA da UE. Sem chave de API, sem cadastro, nada para executar além de HTTP comum.

Eu publiquei isso como uma Skill de Agente aberta. Este post é sobre como funciona e como instalá-la.

Divulgação total desde o início: a API por trás disso, skanfirmy.pl, é meu próprio projeto. É gratuito e sem chave, e eu construí a Skill para que os agentes possam acessá-la tão facilmente quanto uma pessoa acessa o site.

O que é realmente uma Skill de Agente

Uma Skill é apenas uma pasta com um arquivo SKILL.md: um pouco de frontmatter YAML (um nome e uma descrição) e um corpo em markdown com instruções. O Claude lê a descrição e, quando uma tarefa corresponde, ele carrega o corpo e o segue. Não há código para executar e nenhuma dependência para instalar. É mais próximo de um runbook bem escrito do que de um plugin.

Esse formato é portátil. O mesmo SKILL.md funciona no Claude Code, nos aplicativos Claude e através do Agent SDK.

Instale-a

Coloque a pasta em um lugar que o Claude leia as skills:

git clone https://github.com/bartosz-kuc/skanfirmy-mcp

# skills pessoais, todos os projetos
mkdir -p ~/.claude/skills
cp -R skanfirmy-mcp/skill ~/.claude/skills/verify-polish-company

Reinicie o Claude Code e você está pronto. A Skill carrega sozinha quando uma solicitação corresponde, então você não precisa chamá-la pelo nome.

Use-a

Agora você pode simplesmente perguntar em linguagem simples:

o NIP 5260250995 é um contribuinte de IVA ativo, e o que está na sua lista branca?

O Claude pega a Skill e executa a verificação correta. Nos bastidores, é um único GET:

curl "https://skanfirmy.pl/nip/5260250995?format=json"

Isso retorna o status do IVA (ativo, isento ou não registrado), os detalhes da empresa do registro de IVA e as contas bancárias que estão na lista branca oficial ("Biała Lista"). Esses dois fatos, status do IVA e correspondência da conta, são os que decidem se um pagamento B2B polonês é seguro para deduzir, então vale a pena acertar.

A Skill também conhece os outros registros:

• GET /regon/{nip} retorna dados do registro REGON do escritório de estatísticas, e cobre empresários individuais, que não estão no registro judicial.
• GET /nip/{nip} também inclui o registro do KRS (forma legal, capital, endereço, representação).
• GET /vies/{country}/{number} valida um número de IVA da UE através do serviço VIES da Comissão Europeia.

Tudo é um GET simples que responde em JSON quando você adiciona ?format=json. Sem chave, sem conta, sem cota diária.

Por que uma Skill e não apenas documentos

Você poderia colar a lista de endpoints em um prompt toda vez. A Skill faz três coisas que um colar único não faz:

1. Ela ensina ao Claude quando buscar essas verificações, então ela é acionada pela intenção real ("verificar este contratado") em vez de esperar para ser informada da URL.
2. Ela escolhe o endpoint correto. Empresário individual? Isso é /regon, porque o registro judicial não os cobre. Número de IVA estrangeiro? Isso é VIES. Ela codifica essas pequenas decisões para que você não precise.
3. Ela nomeia os literais governamentais para se basear, como o valor do status do IVA, em vez de um rótulo traduzido que quebraria o ramificação.

Há também um servidor MCP em https://skanfirmy.pl/mcp para agentes que falam o Protocolo de Contexto do Modelo, com as mesmas verificações que as ferramentas e a mesma regra de sem chave. A Skill aponta para ele, mas você não precisa dele para o caminho REST.

A parte honesta

Os dados vêm diretamente de fontes oficiais: o Ministério das Finanças para a lista branca do IVA, o Ministério da Justiça para o registro judicial, o escritório de estatísticas (GUS) para REGON e a Comissão Europeia para VIES. skanfirmy.pl é uma ferramenta independente, não uma API governamental oficial, e apenas expõe esses registros em um só lugar com uma única solicitação em vez de quatro.

A Skill é licenciada sob MIT e vive aqui: github.com/bartosz-kuc/skanfirmy-mcp. Se você integrar verificações de empresas em fluxos de trabalho de agentes, eu realmente gostaria de saber o que está faltando.