c9336941ac
Add four skills for Tempo/KSeF timesheet and invoice workflows: - check-my-timesheet: show/log the current user's Tempo time entries - timesheet-checker: audit timesheet completion across all reporters - invoice-checker: pull KSeF invoices, check contractors + MF white list - invoice-prep: summarize Tempo hours per Jira project for invoicing Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
---
|
|
name: invoice-checker
|
|
description: >
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.**
|
|
|
|
```bash
|
|
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).
|