DEV Community: Bartosz Kuć

I packaged Polish company verification as a Claude Skill

Bartosz Kuć — Mon, 24 Aug 2026 10:32:32 +0000

If you use Claude Code or the Claude apps and you ever deal with Polish companies, here is a small thing that saves a surprising amount of time: a Skill that lets Claude verify a company by its tax ID, check whether it is a registered VAT payer, look up its bank account on the government white list, pull its court-register data, and validate an EU VAT number. No API key, no signup, nothing to run beyond ordinary HTTP.

I published it as an open Agent Skill. This post is how it works and how to install it.

Full disclosure up front: the API behind it, skanfirmy.pl, is my own project. It is free and keyless, and I built the Skill so agents can reach it as easily as a person reaches the website.

What an Agent Skill actually is

A Skill is just a folder with a SKILL.md file: a bit of YAML frontmatter (a name and a description) and a markdown body with instructions. Claude reads the description, and when a task matches, it loads the body and follows it. There is no code to execute and no dependency to install. It is closer to a well written runbook than to a plugin.

That format is portable. The same SKILL.md works in Claude Code, in the Claude apps, and through the Agent SDK.

Install it

Drop the folder into a place Claude reads skills from:

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

# personal skills, all projects
mkdir -p ~/.claude/skills
cp -R skanfirmy-mcp/skill ~/.claude/skills/verify-polish-company

Restart Claude Code and you are done. The Skill loads on its own when a request matches, so you do not have to call it by name.

Use it

Now you can just ask in plain language:

is NIP 5260250995 an active VAT payer, and what is on its white list?

Claude picks up the Skill and runs the right check. Under the hood it is a single GET:

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

That returns the VAT status (active, exempt, or not registered), the company details from the VAT register, and the bank accounts that sit on the official white list ("Biała Lista"). Those two facts, VAT status and account match, are the ones that decide whether a Polish B2B payment is safe to deduct, so they are worth getting right.

The Skill knows about the other registers too:

GET /regon/{nip} returns REGON registry data from the statistics office, and it covers sole traders, who are not in the court register.
GET /nip/{nip} also folds in the KRS court record (legal form, capital, address, representation).
GET /vies/{country}/{number} validates an EU VAT number through the European Commission's VIES service.

Everything is a plain GET that answers JSON when you add ?format=json. No key, no account, no daily quota.

Why a Skill and not just docs

You could paste the endpoint list into a prompt every time. The Skill does three things that a one off paste does not:

It teaches Claude when to reach for these checks, so it triggers on the real intent ("verify this contractor") instead of waiting to be told the URL.
It picks the right endpoint. Sole trader? That is /regon, because the court register does not cover them. Foreign VAT number? That is VIES. It encodes those small decisions so you do not have to.
It names the government literals to key off, like the VAT status value, instead of a translated label that would break branching.

There is also an MCP server at https://skanfirmy.pl/mcp for agents that speak the Model Context Protocol, with the same checks as tools and the same no-key rule. The Skill points at it, but you do not need it for the REST path.

The honest part

The data comes straight from official sources: the Ministry of Finance for the VAT white list, the Ministry of Justice for the court register, the statistics office (GUS) for REGON, and the European Commission for VIES. skanfirmy.pl is an independent tool, not an official government API, and it just exposes those registers in one place with one request instead of four.

The Skill is MIT licensed and lives here: github.com/bartosz-kuc/skanfirmy-mcp. If you wire company checks into agent workflows, I would genuinely like to hear what is missing.

Checking Polish companies from code: VAT, KRS, REGON, EU VAT (REST + Python + MCP)

Bartosz Kuć — Sun, 23 Aug 2026 18:18:20 +0000

If you invoice or onboard Polish companies, sooner or later you have to check two dull things that turn out to matter a lot: is this company actually a registered VAT payer, and is the bank account they gave you the one that's on the government's official white list ("Biała Lista")? Both of those affect whether you can deduct the cost and reclaim VAT, so it's not really optional.

The annoying part is that the data lives in four different places: the Ministry of Finance, the KRS court register, GUS (the stats office), and the EU's VIES service. Each one has its own API and its own quirks.

I got tired of gluing those together every time, so I wrapped them behind a few plain HTTP calls that return JSON. Full disclosure: skanfirmy.pl is mine. It's free, no key, no signup, and the web layer runs client-side with no tracking. Here's how you'd actually use it.

REST: one GET, one JSON

Cheapest thing you can do is check a NIP (the tax ID):

curl https://skanfirmy.pl/nip/5260250995

You get back the VAT status (active, exempt, or not registered), the company details from the VAT register, and the accounts sitting on the white list.

The paths:

GET /nip/{nip} gives VAT status + white-list data for one NIP
GET /nips/{list} takes several NIPs at once (comma-separated)
GET /regon/{nip} returns data from the REGON register (GUS)
GET /vies/{country}/{number} validates an EU VAT number, e.g. /vies/DE/811128135

It's a plain GET that returns JSON, so it drops into anything that can make an HTTP request: a cron job, a lambda, a CI step, whatever.

I wrote up the REGON/GUS endpoint on its own page, with examples in a few languages and how it compares to the GUS BIR SOAP service: Polish company data from GUS (REGON) by NIP.

Python

requests and a few lines. This one raises if the company isn't an active VAT payer:

import requests

def check_vat(nip: str) -> dict:
    r = requests.get(f"https://skanfirmy.pl/nip/{nip}", timeout=10)
    r.raise_for_status()
    data = r.json()
    status = data.get("vatStatus") or data.get("status")
    if status != "Czynny":  # status comes back in Polish; compare against the raw value
        raise ValueError(f"NIP {nip}: VAT status = {status!r}")
    return data

result = check_vat("5260250995")
print("White-list accounts:", result.get("accountNumbers", []))

One thing that bit me: the status strings from the Ministry come back in Polish (Czynny = active, Zwolniony = exempt). Compare against the original string, and don't translate before you branch on it, or the check silently breaks the day someone flips the UI language.

Got a big list to run? Use GET /nips/{list}, or the /bulk page if you just need a CSV once.

MCP (for agents)

This is the part I actually built the thing for. There's an MCP server at https://skanfirmy.pl/mcp with 9 tools and no API key, so an agent (say, an accounting assistant) can run the same NIP check a human would click through.

JSON-RPC 2.0 over POST. Calling a tool:

curl -X POST https://skanfirmy.pl/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "sprawdz_nip",
      "arguments": { "nip": "5260250995" }
    }
  }'

tools/list gives you all of them with their input schemas. If your agent only speaks REST, there's an llms.txt at https://skanfirmy.pl/llms.txt describing the endpoints in a model-readable way. And if you need more than the Polish registers, I keep a sister catalog of public APIs aimed at agents over at otwarteapi.pl.

When one check isn't enough

VAT status and white-list accounts change, sometimes day to day, and a one-off check won't tell you when that happens. So there's /monitoring: it diffs daily and pings you over an HMAC-signed webhook when something moves. You verify the signature on your end and react, instead of polling the registers in a loop.

That's basically it

curl for a quick look, requests to put it in code, MCP if an agent is doing the checking. All JSON, no signup, no key. (It's bilingual too: English pages live under /en/, and the REST/MCP endpoints don't care about language either way.)

If you're already solving this differently, especially the white-list account matching, I'd genuinely like to hear how. That part is fiddlier than it looks.