skills-marketplace/plugins/ivona/skills/invoice-checker/SKILL.md

name

description

invoice-checker

Pull and check invoices from KSeF (Krajowy System e-Faktur) for a selected period. For every new invoice checks whether the contractor is in the contractors file and whether the contractor's bank account is on the MF white list (Biała lista podatników VAT). TRIGGER this skill automatically whenever the user mentions pulling, checking, reviewing, or auditing invoices from KSeF — especially when they mention a period like last week, last month, or a date range. Trigger phrases include: "check invoices", "pull invoices", "invoice audit", "KSeF invoices", "check KSeF", "white list check", "biała lista".

Invoice Checker

Use this skill when someone needs to download purchase invoices from KSeF for a given period, verify contractors, and check bank accounts against the MF white list.

In Claude Code, you run the full pipeline automatically. The user provides a period — you handle everything else.

Prerequisites

This skill reads credentials from the .env file in the project root (the working directory where Claude Code is open). The same file is shared with the timesheet-checker skill — just add the KSEF variables to it.

Add these lines to your .env:

# KSeF — Invoice Checker
KSEF_NIP=          # 10-digit company NIP, no dashes
KSEF_TOKEN=        # Authorization token from KSeF portal → Zarządzanie tokenami
KSEF_ENV=prod      # "test" for sandbox, "prod" for production

The variable reference:

Variable	What it is	Where to get it
KSEF_NIP	Company NIP (10 digits, no dashes)	Your company's tax ID
KSEF_TOKEN	KSeF authorization token	KSeF portal → Zarządzanie tokenami
KSEF_ENV	test or prod	Use test for the sandbox, prod for production

The script also requires the cryptography Python package:

pip3 install cryptography

Setup

Determine SKILL_DIR from the location of this file. Set the output directory to ./invoices-output/ in the current working directory. Create it if it does not exist.

Load First

Read these reference files:

1. The contractors config — check ./contractors.md in the current working directory first; if not present, fall back to {SKILL_DIR}/references/contractors.md. Tell the user which one is being used.
2. {SKILL_DIR}/references/output-format.md — the structure of invoices_data.json and the final report.

Extracting the period

The user may express the period in various ways. Convert to YYYY-MM-DD:YYYY-MM-DD before running:

User says	Start	End
"last week"	Last Monday	Last Friday
"last month"	1st of previous month	Last day of previous month
"this month"	1st of current month	Yesterday
"this year"	1 January of current year	Yesterday
"June", "June 2026"	2026-06-01	2026-06-30
Explicit dates	As given	As given

If the user has not specified a period, ask: "Który okres sprawdzić? (np. zeszły tydzień, zeszły miesiąc, zakres dat)"

Workflow

Step 1 — Fetch and check. Run this command:

python3 {SKILL_DIR}/scripts/preprocess.py \
  --period {YYYY-MM-DD:YYYY-MM-DD} \
  --contractors {contractors_path} \
  --output-dir ./invoices-output

This authenticates with KSeF, downloads all purchase invoices for the period, compares against invoices_cache.json to identify new invoices, checks each contractor against contractors.md, checks bank accounts against the MF white list, and writes invoices_data.json to ./invoices-output/.

Step 2 — Interpret. Read ./invoices-output/invoices_data.json. Note:

• New vs known invoices — only new ones (not in cache) are actively checked.
• Unknown contractors — contractors not in contractors.md. Show these to the user and ask if they should be added.
• White list failures — bank accounts not found on the white list. These are high priority — flag them prominently.
• White list errors — API call failed (network issue, etc.). Note that these could not be verified.

Step 3 — Generate report.

python3 {SKILL_DIR}/scripts/postprocess.py \
  --data ./invoices-output/invoices_data.json \
  --output-dir ./invoices-output

This writes invoices_report.md.

Step 4 — Present results. Show the user:

• Summary block: total invoices, new invoices, contractor status, white list status.
• Table of new invoices with contractor and white list status.
• Any white list failures or unknown contractors — highlighted prominently.
• "Full report saved to ./invoices-output/invoices_report.md."

Step 5 — Handle unknown contractors. If the user confirms any unknown contractors should be added, add them to contractors.md. Use the NIP and name from the invoice; leave bank_accounts blank if they want to fill it in later, or populate it from the invoice bank account.

Guardrails

• Never fabricate invoice data. All data comes from KSeF.
• White list checks are always performed against the invoice issue date (not today).
• If KSEF_NIP or KSEF_TOKEN are not set, stop and ask the user for them.
• If the cryptography package is missing, tell the user to run pip3 install cryptography and stop.
• If any script step fails, show the error and stop. Do not proceed with partial output.
• Always terminate the KSeF session even if an error occurs (the script handles this internally).