KSeF Accountant (Polish)

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.

Security Scan

Instruction-only Polish KSeF accounting skill whose declared requirements, metadata, and runtime instructions are consistent with its stated purpose and do not request excessive permissions or installs.

Purpose & Capability

The name/description (KSeF accounting assistant) matches the content: domain guidance, API examples, FA(3) XML examples, workflows and ML design patterns. Declared optional env vars (KSEF_TOKEN, KSEF_ENCRYPTION_KEY, KSEF_BASE_URL) are directly related to integrating with the KSeF API and are reasonable for this scope. No unrelated binaries, credentials, or install steps are requested.

Instruction Scope

SKILL.md and reference docs are instruction-only and repeatedly state they contain examples and must not execute code. The instructions do not direct the agent to read arbitrary host files, system-level config, or transmit data to unexpected endpoints. They explicitly instruct users to verify platform metadata before supplying secrets and to use DEMO by default.

Install Mechanism

No install spec and no included executable code — the skill is pure Markdown with examples. This is the lowest-risk install mechanism and matches the skill's claim of being instruction-only.

Credentials

Environment variables are declared as optional, marked secret, and clearly documented (token, encryption key, base URL). Their presence is proportionate to the function (auth to KSeF, local token encryption). The skill does not require unrelated credentials or high privilege environment paths. The SKILL.md warns users not to paste secrets into conversation and to verify platform handling of secrets.

Persistence & Privilege

The skill declares disableModelInvocation in both frontmatter and skill.json and is not always-enabled; it does not request autonomous invocation. Because the skill is instruction-only and contains no install operations, it does not persist code or modify platform configuration. Note: enforcement of disableModelInvocation depends on the hosting platform (the skill cannot enforce it itself).

Assessment

This skill is an instruction-only KSeF accounting guide and appears internally consistent, but it relies on platform controls to be safe. Before installing: 1) After adding the skill, check the platform's registry view and confirm disable-model-invocation (or equivalent) is set to true and that KSEF_TOKEN / KSEF_ENCRYPTION_KEY are registered as secrets; if the platform shows them as unset or not secret, do NOT provide tokens. 2) Prefer using the demo base URL and test workflows before any production integration. 3) Never paste tokens, keys, or certificates into the chat; use the platform's secret store or a vault and ephemeral/session secrets where possible. 4) If registry metadata shown by the platform differs from the skill's skill.json/frontmatter, treat the skill as higher risk and contact your platform provider. Following those checks makes using this skill appropriate for its stated purpose.

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:

1. 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.
2. 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.
3. Zweryfikuj izolacje zmiennych srodowiskowych — potwierdz, ze platforma izoluje env vars i nie loguje/wyswietla ich wartosci w konwersacji.
4. 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