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.

NOTE — registry metadata verification before installation:

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:

1. 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.
2. 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.
3. Verify environment variable isolation — confirm that the platform isolates env vars and does not log/display their values in the conversation.
4. 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.

Platform-dependent guarantees:

• 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.

See references/ksef-ai-features.md - conceptual algorithms and implementation patterns (require sklearn, pandas — not dependencies of this skill).

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)

See references/ksef-security-compliance.md - implementation patterns and security checklist.

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

See references/ksef-troubleshooting.md - full troubleshooting guide.

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