KSeF Accounting Agent

Specialized knowledge for operating the National e-Invoice System (KSeF) in the KSeF 2.0 environment with the FA(3) structure. Supports accounting tasks related to electronic invoicing in Poland.

Security Model

This skill is instruction-only — it consists of Markdown files containing domain knowledge, architectural patterns and code examples. It does not contain any executable code, binaries, installation scripts or runtime dependencies.

Skill-side guarantees:

• disableModelInvocation: true / disable-model-invocation: true — declared in both the frontmatter metadata (both formats: camelCase and kebab-case) and in the dedicated manifest skill.json. The skill should not be invoked autonomously by the model.
• secret: true — the environment variables KSEF_TOKEN and KSEF_ENCRYPTION_KEY are marked as secrets in the frontmatter and skill.json, signaling to the platform that they must be isolated and must not be logged or displayed.
• No executable code — all examples (Python, XML, JSON) are illustrative, NOT code executed by the skill.
• No installation — the skill does not write files to disk, does not download dependencies, does not modify system configuration.
• Dedicated manifest skill.json — a machine-readable file with security metadata, environment variable declarations and constraints. If the platform does not parse the SKILL.md frontmatter correctly, it should read metadata from skill.json.

Security flags are declared in two sources: the SKILL.md frontmatter and skill.json. Nevertheless, the hosting platform may not read or enforce these flags. Before installation you MUST perform the following steps:

• Check registry metadata — after adding the skill to the platform, open the registry metadata view displayed by the platform. Verify that the disable-model-invocation field is set to true and that the environment variables (KSEF_TOKEN, KSEF_ENCRYPTION_KEY, KSEF_BASE_URL) are visible with the secret label. If the platform shows not set, false or does not display these fields — the flags are NOT enforced.
• If registry metadata does not match frontmatter/skill.json — treat the skill as higher risk: DO NOT provide credentials (tokens, certificates, keys), DO NOT configure environment variables (KSEF_TOKEN, KSEF_ENCRYPTION_KEY), DO NOT allow autonomous use.
• Verify environment variable isolation — confirm that the platform isolates env vars and does not log/display their values in the conversation.
• If the platform does not enforce flags — contact the platform provider to enable support for disableModelInvocation (or parsing of skill.json) or do not install the skill with access to any credentials.

• Enforcement of the disableModelInvocation flag depends on the hosting platform. The frontmatter alone does not provide protection — it requires platform-side support.
• Environment variable (env vars) isolation depends on the platform. The skill declares them as optional but does not control how the platform stores and exposes them.
• If the platform does not enforce these settings, treat the skill as higher risk and do not provide it with credentials or production access.

Constraints

• Knowledge only — no code execution - Provides domain knowledge, architectural patterns and guidance. All code examples (including ML/AI) are educational and illustrative. The skill does NOT run ML models, does NOT perform inference, does NOT require Python/sklearn runtimes or any binaries. The agent explains algorithms and suggests code for the user to implement.
• Not legal or tax advice - Information reflects the state of knowledge at the time of writing and may be outdated. Always recommend consulting a tax advisor before implementation.
• AI assists, does not decide - Descriptions of AI features (expense classification, fraud detection, cash flow prediction) are reference architecture and implementation patterns. The agent provides knowledge about algorithms and helps write code — it does not make binding tax or financial decisions.
• User confirmation required - Always require explicit user consent before: blocking payments, sending invoices to production KSeF, modifying accounting records or any action with financial consequences.
• User-managed credentials - KSeF API tokens, certificates and encryption keys must be provided by the user via environment variables (declared in metadata: KSEF_TOKEN, KSEF_ENCRYPTION_KEY, KSEF_BASE_URL) or a secrets manager. The skill never stores, generates, transmits or implicitly requests credentials. NEVER paste credentials (tokens, keys, certificates) directly in the conversation with the agent — use environment variables or the platform's secrets manager. Vault/Fernet usage examples in the reference documentation are architectural patterns for user implementation.
• Use DEMO for testing - Production (https://ksef.mf.gov.pl) issues legally binding invoices. Use DEMO (https://ksef-demo.mf.gov.pl) for development and testing.
• Autonomous invocation disabled - The skill sets disableModelInvocation: true and disable-model-invocation: true in the frontmatter metadata (both naming formats) and in the dedicated manifest skill.json. This means the model should not invoke this skill autonomously — it requires explicit user action. NOTE: The frontmatter and skill.json are declarations — not guarantees. Enforcement depends on the platform. Before use, verify that the registry metadata displayed by the platform also shows disable-model-invocation: true. If the platform shows not set or false, the flag is not enforced and the skill may be invoked autonomously (see "Security Model" section above).

Pre-installation Checklist

Before installing the skill and configuring environment variables, perform the following steps:

• [ ] Verify platform registry metadata — the disable-model-invocation field must show true
• [ ] Verify that the platform has read env var declarations from the frontmatter or skill.json — the variables KSEF_TOKEN and KSEF_ENCRYPTION_KEY must be visible as secrets (secret: true)
• [ ] Confirm that the platform isolates environment variables (does not log, does not display in conversation)
• [ ] Test the skill exclusively with the DEMO environment (https://ksef-demo.mf.gov.pl) before any production use
• [ ] DO NOT paste tokens, keys or certificates directly in the conversation — use env vars or a secrets manager
• [ ] If registry metadata does not match frontmatter/skill.json — DO NOT configure credentials and report the issue to the platform provider

Core Competencies

1. KSeF 2.0 API Operations

Issuing FA(3) invoices, downloading purchase invoices, managing sessions/tokens, handling Offline24 mode (emergency), downloading UPO (Official Acknowledgement of Receipt).

Key endpoints:

POST /api/online/Session/InitToken     # Session initialization
POST /api/online/Invoice/Send          # Send invoice
GET  /api/online/Invoice/Status/{ref}  # Check status
POST /api/online/Query/Invoice/Sync    # Query purchase invoices

See references/ksef-api-reference.md - full API documentation with authentication, error codes and rate limiting.

2. FA(3) Structure

FA(3) vs FA(2) differences: invoice attachments, EMPLOYEE contractor type, extended bank account formats, 50,000 line item limit for corrections, JST and VAT group identifiers.

See references/ksef-fa3-examples.md - XML examples (basic invoice, multiple VAT rates, corrections, MPP, Offline24, attachments).

3. Accounting Workflows

Sales: Data -> Generate FA(3) -> Send to KSeF -> Get KSeF number -> Post Dr 300 (Receivables) | Cr 700 (Sales) + Cr 220 (Output VAT)

Purchases: Query KSeF -> Download XML -> AI Classification -> Post Dr 400-500 (Expenses) + Dr 221 (VAT) | Cr 201 (Payables)

See references/ksef-accounting-workflows.md - detailed workflows with payment matching, MPP, corrections, VAT registers and month-end closing.

4. AI-Assisted Features (Reference Architecture)

The descriptions below are implementation patterns and reference architecture. The skill does NOT run ML models — it provides knowledge about algorithms, helps design pipelines and write code for implementation in the user's system. Code examples in reference files (Python, sklearn, pandas) are illustrative pseudocode — the skill does not contain trained models, ML artifacts or executable files.

• Expense classification - Pattern: contractor history -> keyword matching -> ML model (Random Forest). Flag for review if confidence < 0.8.
• Fraud detection - Pattern: Isolation Forest for amount anomalies, scoring for phishing invoices, graph analysis for VAT carousel.
• Cash flow prediction - Pattern: Random Forest Regressor based on contractor history, amounts and seasonal patterns.

5. Compliance and Security (Implementation Patterns)

The following are recommended security patterns for implementation in the user's system. The skill provides knowledge and code examples — it does not implement these mechanisms itself.

• VAT White List verification before payments
• Encrypted token storage (Fernet/Vault patterns — for user implementation)
• Audit trail of all operations
• 3-2-1 backup strategy
• GDPR compliance (anonymization after retention period)
• RBAC (role-based access control)

6. Corrective Invoices

Download original from KSeF -> Create FA(3) correction -> Link to original KSeF number -> Send to KSeF -> Post reversal or differential entry.

7. VAT Registers and JPK_V7

Generating sales/purchase registers (Excel/PDF), JPK_V7M (monthly), JPK_V7K (quarterly).

Troubleshooting - Quick Help

Reference Files

Load depending on the task:

Official Resources

• KSeF Portal: https://ksef.podatki.gov.pl
• KSeF DEMO: https://ksef-demo.mf.gov.pl
• KSeF Production: https://ksef.mf.gov.pl
• VAT White List API: https://wl-api.mf.gov.pl
• KSeF Latarnia (status): https://github.com/CIRFMF/ksef-latarnia