Skip to main content
skill CX Codex

nfz — Claude Code skill: waiting lists and installation

This Claude Code skill searches NFZ services and reports estimated waits, queues, and facilities. Query by city or region, or search near a location.

MIT ★ 60 updated 2026-11-15

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add b44x/ai-polish-skills
/plugin install nfz@polskie-skille
Open on GitHub

What nfz does

The skill retrieves NFZ service and queue data through scripts/nfz.py. It looks up official service names, reports estimated waits and patient counts for urgent and stable cases, finds nearby facilities, and compares their queues. The results cover administrative waiting-list information, not medical advice.

PCUŚ reports a statistical estimate, not the date of the next available appointment. The script requires Python 3.8+ and network access to the NFZ API; it uses Python’s standard library and needs no API key. A network or NFZ server error can prevent it from retrieving current data.

What it helps with

  • find NFZ facilities for a medical service
  • check estimated waits in a city
  • compare queues at clinics and hospitals
  • locate facilities within a chosen radius

Example prompts for the agent

  • Find the NFZ MRI queue in Gdańsk and list the facilities.
  • Compare estimated cardiology waits in Warszawa.
  • Locate colonoscopy facilities within 30 km of coordinates 54.35, 18.64.

How to install nfz

1Plugin marketplace

/plugin marketplace add b44x/ai-polish-skills
/plugin install nfz@polskie-skille

This installs the whole nfz plugin with all its skills

2Skills CLI (Vercel)

npx skills add b44x/ai-polish-skills --skill nfz -a claude-code

3Manually: put the files in place

~/.claude/skills/nfz/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nfz/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nfz

How do I install nfz in Claude Code?

Add the marketplace with /plugin marketplace add b44x/ai-polish-skills, then install the skill with /plugin install nfz@polskie-skille.

What does nfz do?

It searches NFZ services, waiting lists, and facilities, then compares estimated waits and distances. PCUŚ is an estimate rather than the date of the next available appointment.

What does nfz need to run?

It needs Python 3.8+ and network access to the NFZ API. No API key is required, and the script uses Python’s standard library.

Source text

SKILL.md · MIT
---
name: nfz
display_name: NFZ Kolejki i Czas Oczekiwania (PCUŚ)
version: 1.0.0
description: >-
  Official data from the Narodowy Fundusz Zdrowia (NFZ, Polish National Health Fund) on queues,
  medical facilities and estimated waiting times for healthcare services (PCUŚ). Search medical
  services (MRI, CT, colonoscopy, gastroscopy, cardiology clinic, orthopedist, ophthalmologist),
  check the estimated waiting time (in days and months) and the number of waiting patients for
  stable and urgent cases. Find the nearest facilities within a given radius in kilometers
  (Haversine) and compare waiting times across hospitals and clinics. No API keys, 100% official
  public data from the NFZ Terminy Leczenia API. Use whenever the user asks about: "kolejki NFZ",
  "czas oczekiwania do kardiologa", "gdzie na rezonans na NFZ", "terminy leczenia",
  "poradnia NFZ w Gdańsku", "najkrótsza kolejka do endokrynologa", "NFZ czas oczekiwania".
category: health
language: pl
country: PL
license: MIT
author: Michell Hoduń (https://github.com/b44x)
repository: https://github.com/b44x/ai-polish-skills
network: true
authentication: none
source: Narodowy Fundusz Zdrowia (NFZ)
source_type: official_api
official: true
homepage: https://terminyleczenia.nfz.gov.pl/
documentation: https://apinfz.nfz.gov.pl/app-itl-api-pcus/
rate_limit: fair use
last_verified: 2026-09-28
tags:
  - nfz
  - zdrowie
  - kolejki
  - pcus
  - lekarz
  - przychodnia
  - szpital
  - rezonans
  - tomografia
  - kardiolog
  - stomatolog
  - terminy
compatibility: Python 3.8+ (standard library only); network access to apinfz.nfz.gov.pl.
---

# NFZ Queues and Waiting Times (PCUŚ)

Official skill integrating open data from the Narodowy Fundusz Zdrowia (NFZ) Terminy Leczenia / PCUŚ v1.4 API
via the `scripts/nfz.py` tool. Works without registration and without API keys, uses only the Python standard
library, and returns structured JSON on `stdout`.

> **Important:** PCUŚ (*Prognozowany Czas Oczekiwania na Świadczenie*, estimated waiting time for a service)
> is a statistical estimate calculated by NFZ — it is **not** the date of the first free appointment.

## Running the script

Run from the skill directory (or from the repository root path):

| Operating system | Command |
|---|---|
| Linux / macOS | `python3 scripts/nfz.py <command> …` |
| Windows | `py scripts/nfz.py <command> …` (or `python`) |

Zero external libraries (Python 3.8+ stdlib).

## Workflow

1. **Looking up the official service name:**
   - When the user asks generally about a test or specialty (e.g. „rezonans”, „kardiolog”, „kolonoskopia”):
     `python3 scripts/nfz.py benefits rezonans`
     `python3 scripts/nfz.py benefits kardiolog`
     `python3 scripts/nfz.py benefits kolonoskopia`
   - Returns a list of official NFZ service names that can be passed to subsequent queries.

2. **Queues and waiting times in a given city / voivodeship (województwo):**
   - Checking the waiting time for a service in a specific city:
     `python3 scripts/nfz.py queues --benefit "REZONANS MAGNETYCZNY" --locality Gdańsk`
     `python3 scripts/nfz.py queues --benefit "ŚWIADCZENIA Z ZAKRESU KARDIOLOGII" --locality Warszawa`
   - Filtering for an urgent case (urgent / "cito" referral):
     `python3 scripts/nfz.py queues --benefit "REZONANS MAGNETYCZNY" --locality Gdańsk --urgent`

3. **Geographic search for facilities within a radius in kilometers (`near`):**
   - Finding facilities providing a given service within a radius of a given city or coordinates:
     `python3 scripts/nfz.py near Gdańsk --benefit "rezonans" --radius-km 50`
     `python3 scripts/nfz.py near 54.35 18.64 --benefit "kolonoskopia" --radius-km 30`
   - Sorting by shortest waiting time (`--sort time`) or smallest distance (`--sort distance`).

4. **Comparing facilities and shortest queues (`compare`):**
   - Side-by-side comparison of facilities, highlighting the facility with the shortest waiting time:
     `python3 scripts/nfz.py compare --benefit "rezonans" --locality Gdańsk`
     `python3 scripts/nfz.py compare --benefit "kardiolog" --province pomorskie`

5. **List of NFZ voivodeship codes (`provinces`):**
   - Overview of the 16 NFZ codes (e.g. `11` for pomorskie, `07` for mazowieckie):
     `python3 scripts/nfz.py provinces`

## Commands

| Command | Description | Returned data |
|---|---|---|
| `benefits <query>` | Dictionary of official service names | `query`, `count`, `benefits` |
| `queues [--benefit B] [--province P] [--locality L] [--urgent]` | Waiting times and list of facilities | `place`, `provider`, `locality`, `address`, `phone`, `waitingTime` (`pcus`, `averagePeriodDays`, `awaiting`), `accessibility` |
| `near <location\|lat> [lon] --benefit <B> [--radius-km R]` | Facilities within a radius in km, with distances | Facility objects with computed `distanceKm`, sorted by the chosen criterion |
| `compare --benefit <B> [--locality L] [--province P]` | Comparative summary of facilities | `highlights` (`shortestWaitClinic`, `fewestAwaitingClinic`, `closestClinic`), list of facilities |
| `provinces` | Dictionary of the 16 voivodeships and NFZ codes | Two-digit codes and voivodeship names (offline) |

Detailed description of JSON schemas: [references/output.md](references/output.md).

## Exit codes

Clean JSON goes to `stdout`; errors go to `stderr` as `{"error": "...", "type": "..."}`.

| Code | Meaning | Action |
|---|---|---|
| `0` | Success | Use the JSON data from `stdout` |
| `2` | Not found | No facilities or no such service in the NFZ register |
| `64` | Invalid invocation / validation | Check the parameters (min. 3-character phrase, valid voivodeship code) |
| `69` | NFZ server / network error | `apinfz.nfz.gov.pl` API error or network problem |

## Rules

- **Always cite the data source:** Narodowy Fundusz Zdrowia (NFZ / Terminy Leczenia).
- **Distinguish PCUŚ from an appointment date:** NFZ data presents the *Prognozowany Czas Oczekiwania na Świadczenie* (a statistical time calculated by NFZ based on recent months), not a guaranteed first free appointment. Explain this to the user.
- **Medical neutrality:** The tool provides administrative queue data. Do not make medical diagnoses or assess the quality of care at a given facility.
- **Recommend a phone call:** Suggest that the user contact the facility's registration desk directly by phone (number given in the `phone` field) before going there in person.

© Michell Hoduń (https://github.com/b44x) · MIT · b44x/ai-polish-skills

Similar skills

All skills for Backend and APIs →

From the same set52

The whole set →
nieruchomosci The nieruchomosci Claude Code skill searches Poland’s RCN register for property transactions. Set a coordinate area and filter records by deed date, market, or size. CX Codex +1 ★ 60repo stars sejm This Claude Code skill queries the Polish Sejm’s official API. The agent uses it to look up MPs, voting records, bills and parliamentary interpellations. CX Codex +1 ★ 60repo stars prawo The prawo Claude Code skill looks up Polish laws through the Sejm’s official API. It finds articles, act status, and amendment details. CX Codex +1 ★ 60repo stars imgw This Claude Code skill retrieves IMGW-PIB weather, warning and river-level data for Poland. It responds to requests about local conditions, alerts or water levels. CX Codex +1 ★ 60repo stars apteki The apteki Claude Code skill searches Poland’s official pharmacy registry export. It responds to requests for a pharmacy’s address, phone number, or registry status. CX Codex +1 ★ 60repo stars produkty The produkty Claude Code skill retrieves food-label details from a barcode or a product name. It queries Open Food Facts for ingredient, allergen-tag and nutrition data, with Poland as the default declared sales-country filter. CX Codex +1 ★ 60repo stars leki The leki Claude Code skill searches Poland’s official RPL medicine register by product name, declared active substance, or GTIN/EAN. It returns matching products, package records, and publisher document links. CX Codex +1 ★ 60repo stars ceny-deweloperow The ceny-deweloperow Claude Code skill reconstructs a home’s observed asking-price history from developer price lists. It reports dated changes and gaps in the available records. CX Codex +1 ★ 60repo stars

Project sponsors

Companies that keep this analytics open