| name | ksef-accountant-pl |
| description | 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. |
| homepage | https://github.com/alexwoo-awso/skills |
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 lub , 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:
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
