nbp — Claude Code skill for NBP rates and installation
The nbp skill for Claude Code retrieves Narodowy Bank Polski exchange rates and gold prices. It handles currency conversions and invoice tax calculations in PLN.
MIT ★ 60 updated 2026-11-15
/plugin marketplace add b44x/ai-polish-skills
/plugin install nbp@polskie-skilleWhat nbp does
The skill fetches official NBP currency rates, converts amounts between currencies, and returns gold prices per gram and troy ounce. It activates for requests about exchange rates, invoice conversion, or gold prices.
For an invoice, scripts/nbp.py selects the rate from the last business day before its date, skipping weekends and holidays. Commands return structured JSON. It requires Python 3.8 or later and network access to api.nbp.pl; the script uses only Python’s standard library.
What it helps with
- retrieve a current or historical NBP currency rate
- convert a foreign-currency invoice amount to PLN by invoice date
- exchange an amount between two currencies
- get NBP gold prices per gram and troy ounce
Example prompts for the agent
- Get today’s official EUR rate from NBP.
- Convert my 1500 EUR invoice dated 2026-09-28 to PLN.
- Find the NBP gold price per gram and per troy ounce.
How to install nbp
1Plugin marketplace
/plugin marketplace add b44x/ai-polish-skills/plugin install nbp@polskie-skilleThis installs the whole nbp plugin with all its skills
2Skills CLI (Vercel)
npx skills add b44x/ai-polish-skills --skill nbp -a claude-code3Manually: put the files in place
~/.claude/skills/nbp/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nbp/
1Skills CLI (Vercel)
npx skills add b44x/ai-polish-skills --skill nbp -a codex2Manually: put the files in place
.agents/skills/nbp/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add b44x/ai-polish-skills --skill nbp -a cursor2Manually: put the files in place
.cursor/skills/nbp/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install b44x/ai-polish-skills skills/nbp2Manually: put the files in place
.github/skills/nbp/SKILL.md1Skills CLI (Vercel)
npx skills add b44x/ai-polish-skills --skill nbp -a gemini-cli2Platform CLI
gemini skills install https://github.com/b44x/ai-polish-skills --path skills/nbpManually: put the files in place
.devin/skills/nbp/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about nbp
How do I install nbp in Claude Code?
Run /plugin marketplace add b44x/ai-polish-skills followed by /plugin install nbp@polskie-skille.
What does nbp do?
It retrieves NBP exchange rates and gold prices, converts amounts, and calculates invoice values in PLN using the rate from the last business day before the invoice date.
What does nbp need to run?
It requires Python 3.8 or later and network access to api.nbp.pl. It uses Python’s standard library.
Source text
SKILL.md · MIT
---
name: nbp
display_name: Narodowy Bank Polski (NBP)
version: 1.0.0
description: >-
Fetch official exchange rates, calculate tax conversions for foreign currency invoices,
and check gold prices from Narodowy Bank Polski (NBP). Get current or historical average
rates (Table A & B) for EUR, USD, GBP, CHF, etc. Calculate foreign currency invoices in
PLN according to Polish tax law (Art. 31a ustawy o VAT / Art. 11a ustawy o PIT) by
automatically looking up the official NBP rate from the last business day preceding the
invoice date. Convert between any currency pairs. Get official gold prices per gram and
troy ounce. Use whenever the user asks about "kurs euro", "kurs dolara", "tabela NBP",
"kurs do faktury", "przelicz walutę NBP", "cena złota NBP", or foreign invoice conversion.
category: finance
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 Bank Polski
source_type: official_api
official: true
homepage: https://nbp.pl
documentation: https://api.nbp.pl/
rate_limit: fair use
last_verified: 2026-09-28
tags:
- nbp
- waluty
- kursy-walut
- euro
- dolar
- podatki
- vat
- zloto
- faktury
compatibility: Python 3.8+ (standard library only); network access to api.nbp.pl.
---
# Narodowy Bank Polski (NBP)
Fetches official currency exchange rates and gold prices from Narodowy Bank Polski using
`scripts/nbp.py`. Always outputs structured JSON.
## Running the script
Run from this skill's directory (or use relative path from repo root):
| OS | Command |
|---|---|
| Linux / macOS | `python3 scripts/nbp.py <command> …` |
| Windows | `py scripts/nbp.py <command> …` (or `python`) |
Zero external dependencies required (standard library only).
## Workflow
1. **Foreign Currency Invoices (Tax conversion):**
- Whenever the user asks to convert an invoice or calculate VAT/income tax for a foreign currency:
`python3 scripts/nbp.py invoice <amount> <currency> <invoice_date>`
*Example:* `python3 scripts/nbp.py invoice 1500 EUR 2026-09-28`
- The script automatically locates the official NBP table published on the **last business day preceding the invoice date** (skipping weekends and holidays) in accordance with Art. 31a ust. 1 Ustawy o VAT.
- Always report the `tableNumber`, `taxEffectiveDate`, `exchangeRate`, and `amountPln`.
2. **Single Currency Rate:**
- User asks for the current or historical rate of a currency (e.g. "ile kosztuje euro dzisiaj?"):
`python3 scripts/nbp.py rate EUR`
`python3 scripts/nbp.py rate USD --date 2026-09-15`
3. **General Currency Conversion:**
- Convert arbitrary amounts between currencies:
`python3 scripts/nbp.py convert 250 USD EUR`
4. **Gold Price:**
- User asks for gold prices:
`python3 scripts/nbp.py gold`
- Returns official NBP price per 1 gram and calculated per troy ounce (oz) in PLN.
5. **Full Tables:**
- List all rates from Table A (major) or B (exotic):
`python3 scripts/nbp.py table A`
## Commands
| Command | Description | Returns |
|---|---|---|
| `invoice <amount> <currency> <date>` | Convert invoice to PLN according to Polish tax law (preceding business day) | `invoiceDate`, `taxEffectiveDate`, `tableNumber`, `exchangeRate`, `amountPln`, `legalBasis` |
| `rate <currency> [--date D]` | Get mid exchange rate for currency (Table A or B) | `currency`, `mid`, `tableNumber`, `effectiveDate` |
| `convert <amount> <from> <to> [--date D]` | Convert between any two currencies | `amount`, `convertedAmount`, `effectiveRate`, `date` |
| `table [A\|B\|C] [--date D]` | Fetch complete exchange rates table | `tableNumber`, `effectiveDate`, `rates` list |
| `gold [--date D]` | Get official gold price in PLN (per gram and troy ounce) | `pricePerGramPln`, `pricePerTroyOuncePln`, `priceFormatted` |
Field reference and statutory tax rules: [references/output.md](references/output.md).
## Exit codes
JSON goes to stdout; errors go to stderr as `{"error": "...", "type": "..."}`.
| Code | Meaning | What to do |
|---|---|---|
| `0` | Success | Use the JSON output |
| `2` | Not found | Invalid currency code or date out of range / holiday |
| `64` | Bad usage / validation | Invalid date format (expected YYYY-MM-DD) or missing arguments |
| `69` | Network / NBP server error | Retry once; check internet connection |
## Rules
- For tax and invoicing questions, always use `invoice` rather than `rate` — Polish tax law strictly forbids using the rate from the same day as the invoice.
- Cite the official `tableNumber` (e.g. `187/A/NBP/2026`) in your answer to ensure full legal audit compliance.
© Michell Hoduń (https://github.com/b44x) · MIT · b44x/ai-polish-skills