Skills ksef-accountant-pl

Asystent ksiegowy Krajowego Systemu e-Faktur (KSeF) w jezyku polskim. Uzyj przy pracy z KSeF 2.0 API, fakturami FA(3), zgodnoscia z polskim VAT, przetwarzaniem e-faktur, dopasowywaniem platnosci, rejestrami VAT (JPK_V7), fakturami korygujacymi, mechanizmem podzielonej platnosci (MPP) lub polskimi przeplywami ksiegowymi. Dostarcza wiedze domenowa do wystawiania faktur, przetwarzania zakupow, klasyfikacji kosztow, wykrywania fraudu i prognozowania cash flow w ekosystemie KSeF.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/alexwoo-awso/ksef-accountant-pl" ~/.claude/skills/clawdbot-skills-ksef-accountant-pl && rm -rf "$T"

manifest: skills/alexwoo-awso/ksef-accountant-pl/SKILL.md

source content

Agent Ksiegowy KSeF

Specjalistyczna wiedza do obslugi Krajowego Systemu e-Faktur (KSeF) w srodowisku KSeF 2.0 ze struktura FA(3). Wspiera zadania ksiegowe zwiazane z fakturowaniem elektronicznym w Polsce.

Model bezpieczenstwa

Ten skill jest wylacznie instrukcyjny — sklada sie z plikow Markdown zawierajacych wiedze domenowa, wzorce architektoniczne i przyklady kodu. Nie zawiera zadnego kodu wykonywalnego, binarek, skryptow instalacyjnych ani zaleznosci runtime.

Gwarancje po stronie skilla:

```
disableModelInvocation: true
```
/
```
disable-model-invocation: true
```
— zadeklarowane zarowno w metadanych frontmatter (oba formaty: camelCase i kebab-case) jak i w dedykowanym manifescie
```
skill.json
```
. Skill nie powinien byc wywolywany autonomicznie przez model.
```
secret: true
```
— zmienne srodowiskowe
```
KSEF_TOKEN
```
i
```
KSEF_ENCRYPTION_KEY
```
sa oznaczone jako sekrety w frontmatter i
```
skill.json
```
, sygnalizujac platformie, ze musza byc izolowane i nie moga byc logowane ani wyswietlane.
Brak kodu wykonywalnego — wszystkie przyklady (Python, XML, JSON) to ilustracje pogladowe, NIE kod uruchamiany przez skill.
Brak instalacji — skill nie zapisuje plikow na dysk, nie pobiera zaleznosci, nie modyfikuje konfiguracji systemu.
Dedykowany manifest
```
skill.json
```
— maszynowo czytelny plik z metadanymi bezpieczenstwa, deklaracjami zmiennych srodowiskowych i ograniczeniami. Jesli platforma nie parsuje frontmatter SKILL.md poprawnie, powinna odczytac metadane z
```
skill.json
```
.

UWAGA — weryfikacja metadanych rejestru przed instalacja:

Flagi bezpieczenstwa sa zadeklarowane w dwoch zrodlach: frontmatter SKILL.md i

skill.json

. Mimo to, platforma hostingowa moze nie odczytac lub nie wymusic tych flag. Przed instalacja MUSISZ wykonac ponizsze kroki:

Sprawdz metadane rejestru — po dodaniu skilla do platformy, otworz widok metadanych rejestru (registry metadata) wyswietlany przez platforme. Zweryfikuj, ze pole
```
disable-model-invocation
```
jest ustawione na
```
true
```
oraz ze zmienne srodowiskowe (
```
KSEF_TOKEN
```
,
```
KSEF_ENCRYPTION_KEY
```
,
```
KSEF_BASE_URL
```
) sa widoczne z oznaczeniem
```
secret
```
. Jesli platforma pokazuje
```
not set
```
,
```
false
```
lub nie wyswietla tych pol — flagi NIE sa wymuszane.
Jesli metadane rejestru nie pasuja do frontmatter/skill.json — traktuj skill jako wyzszego ryzyka: NIE udostepniaj danych uwierzytelniajacych (tokenow, certyfikatow, kluczy), NIE konfiguruj zmiennych srodowiskowych (
```
KSEF_TOKEN
```
,
```
KSEF_ENCRYPTION_KEY
```
), NIE zezwalaj na autonomiczne uzycie.
Zweryfikuj izolacje zmiennych srodowiskowych — potwierdz, ze platforma izoluje env vars i nie loguje/wyswietla ich wartosci w konwersacji.
Jesli platforma nie wymusza flag — skontaktuj sie z dostawca platformy w celu wlaczenia obslugi
```
disableModelInvocation
```
(lub parsowania
```
skill.json
```
) lub nie instaluj skilla z dostepem do jakichkolwiek danych uwierzytelniajacych.

Gwarancje zalezne od platformy:

Wymuszanie flagi
```
disableModelInvocation
```
zalezy od platformy hostingowej. Sam frontmatter nie zapewnia ochrony — wymaga wsparcia po stronie platformy.
Izolacja zmiennych srodowiskowych (env vars) zalezy od platformy. Skill deklaruje je jako opcjonalne, ale nie kontroluje jak platforma je przechowuje i udostepnia.
Jesli platforma nie wymusza tych ustawien, traktuj skill jako wyzszego ryzyka i nie udostepniaj mu danych uwierzytelniajacych ani dostepu produkcyjnego.

Ograniczenia

Tylko wiedza — brak wykonywania kodu - Dostarcza wiedze domenowa, wzorce architektoniczne i wskazowki. Wszystkie przyklady kodu (w tym ML/AI) sa edukacyjne i pogladowe. Skill NIE uruchamia modeli ML, NIE wykonuje inferencji, NIE wymaga runtime'ow Python/sklearn ani zadnych binarek. Agent wyjasnia algorytmy i sugeruje kod do implementacji przez uzytkownika.
Nie jest porada prawna ani podatkowa - Informacje odzwierciedlaja stan wiedzy na dzien sporadzenia i moga byc nieaktualne. Zawsze zalecaj konsultacje z doradca podatkowym przed wdrozeniem.
AI wspiera, nie decyduje - Opisy funkcji AI (klasyfikacja kosztow, wykrywanie fraudu, predykcja cash flow) to architektura referencyjna i wzorce implementacyjne. Agent dostarcza wiedze o algorytmach i pomaga pisac kod — nie podejmuje wiazacych decyzji podatkowych ani finansowych.
Wymagane potwierdzenie uzytkownika - Zawsze wymagaj jawnej zgody uzytkownika przed: blokowaniem platnosci, wysylaniem faktur na produkcyjny KSeF, modyfikacja zapisow ksiegowych lub jakimkolwiek dzialaniem z konsekwencjami finansowymi.
Dane uwierzytelniajace zarzadzane przez uzytkownika - Tokeny KSeF API, certyfikaty i klucze szyfrowania musza byc dostarczone przez uzytkownika przez zmienne srodowiskowe (zadeklarowane w metadanych:
```
KSEF_TOKEN
```
,
```
KSEF_ENCRYPTION_KEY
```
,
```
KSEF_BASE_URL
```
) lub menedzer sekretow. Skill nigdy nie przechowuje, nie generuje, nie przesyla ani nie prosi o dane uwierzytelniajace niejawnie. NIGDY nie wklejaj danych uwierzytelniajacych (tokenow, kluczy, certyfikatow) bezposrednio w rozmowie z agentem — uzyj zmiennych srodowiskowych lub menedzera sekretow platformy. Przyklady uzycia Vault/Fernet w dokumentacji referencyjnej to wzorce architektoniczne do implementacji przez uzytkownika.
Uzyj DEMO do testow - Produkcja (
```
https://ksef.mf.gov.pl
```
) wystawia prawnie wiazace faktury. Uzyj DEMO (
```
https://ksef-demo.mf.gov.pl
```
) do developmentu i testow.
Wylaczone autonomiczne wywolanie - Skill ustawia
```
disableModelInvocation: true
```
i
```
disable-model-invocation: true
```
w metadanych frontmatter (oba formaty nazewnictwa) oraz w dedykowanym manifescie
```
skill.json
```
. Oznacza to, ze model nie powinien wywolywac tego skilla autonomicznie — wymaga jawnej akcji uzytkownika. UWAGA: Frontmatter i
```
skill.json
```
to deklaracje — nie gwarancje. Wymuszanie zalezy od platformy. Przed uzyciem zweryfikuj, ze metadane rejestru (registry metadata) wyswietlane przez platforme rowniez pokazuja
```
disable-model-invocation: true
```
. Jesli platforma pokazuje
```
not set
```
lub
```
false
```
, flaga nie jest wymuszana i skill moze byc wywolywany autonomicznie (patrz sekcja "Model bezpieczenstwa" powyzej).

Checklist przed instalacja

Przed instalacja skilla i konfiguracja zmiennych srodowiskowych wykonaj ponizsze kroki:

Zweryfikuj metadane rejestru platformy — pole
```
disable-model-invocation
```
musi pokazywac
```
true
```
Zweryfikuj, ze platforma odczytala deklaracje env vars z frontmatter lub
```
skill.json
```
— zmienne
```
KSEF_TOKEN
```
i
```
KSEF_ENCRYPTION_KEY
```
musza byc widoczne jako sekrety (
```
secret: true
```
)
Potwierdz, ze platforma izoluje zmienne srodowiskowe (nie loguje, nie wyswietla w konwersacji)
Przetestuj skill wylacznie ze srodowiskiem DEMO (
```
https://ksef-demo.mf.gov.pl
```
) przed jakimkolwiek uzyciem produkcyjnym
NIE wklejaj tokenow, kluczy ani certyfikatow bezposrednio w rozmowie — uzyj env vars lub menedzera sekretow
Jesli metadane rejestru nie pasuja do frontmatter/skill.json — NIE konfiguruj danych uwierzytelniajacych i zglos problem dostawcy platformy

Glowne kompetencje

1. Obsluga KSeF 2.0 API

Wystawianie faktur FA(3), pobieranie faktur zakupowych, zarzadzanie sesjami/tokenami, obsluga trybu Offline24 (awaryjny), pobieranie UPO (Urzedowe Poswiadczenie Odbioru).

Kluczowe endpointy:

POST /api/online/Session/InitToken     # Inicjalizacja sesji
POST /api/online/Invoice/Send          # Wyslanie faktury
GET  /api/online/Invoice/Status/{ref}  # Sprawdzenie statusu
POST /api/online/Query/Invoice/Sync    # Zapytanie o faktury zakupowe

Zobacz references/ksef-api-reference.md - pelna dokumentacja API z uwierzytelnianiem, kodami bledow i rate limiting.

2. Struktura FA(3)

Roznice FA(3) vs FA(2): zalaczniki do faktur, typ kontrahenta PRACOWNIK, rozszerzone formaty konta bankowego, limit 50 000 pozycji w korekcie, identyfikatory JST i grup VAT.

Zobacz references/ksef-fa3-examples.md - przyklady XML (faktura podstawowa, wiele stawek VAT, korekty, MPP, Offline24, zalaczniki).

3. Przeplywy ksiegowe

Sprzedaz: Dane -> Generuj FA(3) -> Wyslij KSeF -> Pobierz nr KSeF -> Ksieguj

Wn 300 (Rozrachunki) | Ma 700 (Sprzedaz) + Ma 220 (VAT nalezny)

Zakupy: Odpytuj KSeF -> Pobierz XML -> Klasyfikuj AI -> Ksieguj

Wn 400-500 (Koszty) + Wn 221 (VAT) | Ma 201 (Rozrachunki)

Zobacz references/ksef-accounting-workflows.md - szczegolowe przeplywy z dopasowywaniem platnosci, MPP, korektami, rejestrami VAT i zamknieciem miesiaca.

4. Funkcje wspomagane AI (architektura referencyjna)

Ponizsze opisy to wzorce implementacyjne i architektura referencyjna. Skill NIE uruchamia modeli ML — dostarcza wiedze o algorytmach, pomaga projektowac pipeline'y i pisac kod do implementacji w systemie uzytkownika. Przyklady kodu w plikach referencyjnych (Python, sklearn, pandas) to pseudokod pogladowy — skill nie zawiera wytrenowanych modeli, artefaktow ML ani plikow wykonywalnych.

Klasyfikacja kosztow - Wzorzec: historia kontrahenta -> dopasowanie slow kluczowych -> model ML (Random Forest). Flaguj do przegladu jesli confidence < 0.8.
Wykrywanie fraudu - Wzorzec: Isolation Forest dla anomalii kwotowych, scoring dla phishing invoices, analiza grafow dla VAT carousel.
Predykcja cash flow - Wzorzec: Random Forest Regressor na podstawie historii kontrahenta, kwot i wzorcow sezonowych.

Zobacz references/ksef-ai-features.md - koncepcyjne algorytmy i wzorce implementacji (wymagaja sklearn, pandas — nie sa zaleznoscia tego skilla).

5. Compliance i bezpieczenstwo (wzorce implementacyjne)

Ponizsze to rekomendowane wzorce bezpieczenstwa do implementacji w systemie uzytkownika. Skill dostarcza wiedze i przyklady kodu — nie implementuje tych mechanizmow sam.

Weryfikacja Bialej Listy VAT przed platnosciami
Szyfrowane przechowywanie tokenow (wzorce Fernet/Vault — do implementacji przez uzytkownika)
Audit trail wszystkich operacji
Strategia backup 3-2-1
Zgodnosc z RODO (anonimizacja po okresie retencji)
RBAC (kontrola dostepu oparta na rolach)

Zobacz references/ksef-security-compliance.md - wzorce implementacji i checklista bezpieczenstwa.

6. Faktury korygujace

Pobierz oryginal z KSeF -> Utworz korekte FA(3) -> Powiaz z nr KSeF oryginalu -> Wyslij do KSeF -> Ksieguj storno lub roznicowo.

7. Rejestry VAT i JPK_V7

Generowanie rejestrow sprzedazy/zakupow (Excel/PDF), JPK_V7M (miesieczny), JPK_V7K (kwartalny).

Troubleshooting - szybka pomoc

Problem	Przyczyna	Rozwiazanie
Faktura odrzucona (400/422)	Nieprawidlowy XML, NIP, data, brak pol	Sprawdz UTF-8, waliduj schemat FA(3), weryfikuj NIP
Timeout API	Awaria KSeF, siec, godziny szczytu	Sprawdz status KSeF, retry z exponential backoff
Nie mozna dopasowac platnosci	Niezgodna kwota, brak danych, split payment	Rozszerzone wyszukiwanie (+/-2%, +/-14 dni), sprawdz MPP

Zobacz references/ksef-troubleshooting.md - pelny przewodnik troubleshooting.

Pliki referencyjne

Laduj w zaleznosci od zadania:

Plik	Kiedy czytac
skill.json	Manifest metadanych — flagi bezpieczenstwa, deklaracje env vars, ograniczenia. Zrodlo prawdy dla rejestrow i skanerow.
ksef-api-reference.md	Endpointy KSeF API, uwierzytelnianie, wysylanie/pobieranie faktur
ksef-legal-status.md	Daty wdrozenia KSeF, wymagania prawne, kary
ksef-fa3-examples.md	Tworzenie lub walidacja struktur XML faktur FA(3)
ksef-accounting-workflows.md	Zapisy ksiegowe, dopasowanie platnosci, MPP, korekty, rejestry VAT
ksef-ai-features.md	Klasyfikacja kosztow, wykrywanie fraudu, algorytmy predykcji cash flow
ksef-security-compliance.md	Biala Lista VAT, bezpieczenstwo tokenow, audit trail, RODO, backup
ksef-troubleshooting.md	Bledy API, problemy walidacji, wydajnosc

Zasoby oficjalne

Portal KSeF: https://ksef.podatki.gov.pl
KSeF DEMO: https://ksef-demo.mf.gov.pl
KSeF Produkcja: https://ksef.mf.gov.pl
API Bialej Listy VAT: https://wl-api.mf.gov.pl
KSeF Latarnia (status): https://github.com/CIRFMF/ksef-latarnia