timerise-ai

Ksef — Development skill for Claude Code

Development community

Claude Code skill: build KSeF API 2.0 integrations (Krajowy System e-Faktur, Poland's national e-invoicing) — KSeF-token auth, AES/RSA invoice encryption, interactive and batch sending, UPO receipts.

How to install Ksef

This entry records only its repository, not the path inside it, so there is no exact command to give. Open timerise-ai/ksef and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Ksef does

Alternatives in Development

Happy — Mobile and Web client for Claude Code, with realtime voice, encryption and fully featured 16.3k ★
Doctor — Environment diagnostics with interactive fixes — providers, auth, RTK, hooks, token optimization 2.8k ★
Claude Code Everything You Need To Know — Ultimate all-in-one guide to mastering Claude Code 1.3k ★

README

ksef

A [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) that teaches an agent to build **KSeF API 2.0** integrations (Krajowy System e-Faktur — Poland's national e-invoicing system) in a **Next.js App Router** app on Vercel — KSeF-token auth, AES/RSA invoice encryption, interactive and batch sending, UPO receipts, incremental purchase-invoice sync, QR verification codes, and the cron-polling architecture serverless forces on you. Official SDKs exist for C# and Java only; this is the TypeScript equivalent.

A KSeF integration has one hard requirement: **an invoice that leaves your app is a legally binding tax document**, filed under a taxpayer's NIP, and nothing in the API checks that the taxpayer is yours. Every defect the field report behind version 1.1.0 turned up broke that requirement quietly rather than loudly: an IV prepended to the ciphertext, so KSeF rejected the invoice with a status code blaming its *size*; a `440` duplicate whose UPO lived in a session the code never looked in; a seller NIP that nobody compared to the authenticating context. The references are written so those cost you a paragraph instead of a week.

Install

Clone into your skills directory:

git clone https://github.com/timerise-ai/ksef.git ~/.claude/skills/ksef

The [skills index](https://github.com/timerise-ai/skills) lists the other Timerise skills and how to clone them all at once.

The skill activates automatically when a task matches its description — sending or receiving structured invoices, KSeF auth, UPO, FA(3), e-faktura, `ksef.mf.gov.pl`. You can also invoke it explicitly with `/ksef`.

What's inside

File	Contents
`SKILL.md`	Entry point: critical facts, environments, quick start, and the reference directory
`references/architecture-and-vercel.md`	Start here for greenfield: system model, database DDL, cron polling, multi-tenancy, function limits, go-live
`references/crypto-and-client.md`	`node:crypto`