Agentic Ventures Wiki

SKILL

3 Min. Lesezeit

beleg-erstellen — Skill

Generiert Angebote, Rechnungen und Gutschriften im einheitlichen AV-Stripe-Look. Templates + Validator + Build-Script liegen alle in diesem Ordner — ein YAML rein, ein PDF raus.

Wann triggern

Bei jeder Beleg-Erstellung an Kunden:

  • Angebote (Pre-Sales): kein gesetzlicher Zwang, aber Konsistenz-Checks (Empfaenger, Konditionen, Anlagen)
  • Rechnungen (Post-Sales): § 14 UStG Pflichtangaben werden hart geprueft, sonst kein Build
  • Gutschriften (Korrektur/Storno): wie Rechnung, plus Bezug zur urspruenglichen Rechnung Pflicht

Wie nutzen

1. Stammdaten einmalig pflegen

stammdaten.yaml ist die Single Source of Truth fuer alles was sich nicht pro Beleg aendert:

  • Absender (Firma, Anschrift, Geschaeftsfuehrer, Email, Web)
  • Recht (Sitz, Amtsgericht, HRB, USt-IdNr, Steuernummer, Kleinunternehmer-Flag)
  • Bank (IBAN, BIC, Bank-Name)
  • Steuer (Default-Satz, Reverse-Charge-Text, Kleinunternehmer-Text)
  • Zahlung (Standard-Zahlungsziel)
  • Nummerierung (Format-Strings fuer Beleg-Nummern)

Wenn sich was aendert (USt-IdNr da, UG eingetragen, IBAN, etc.):

  • Nur hier aendern
  • history-Block ergaenzen (GoBD: nachvollziehbare Aenderung)
  • Alle kuenftigen Belege ziehen die neuen Werte automatisch

2. Neuen Beleg anlegen

Nimm das passende Beispiel als Vorlage und passe an:

cp beispiele/2026-05-21-angebot-woehrle.yaml \
   beispiele/$(date +%Y-%m-%d)-angebot-<kunde>.yaml

Editiere die YAML, dann build:

cd intern/capabilities/skills/beleg-erstellen
python3 build.py beispiele/<datei>.yaml \
  --out /Users/marvinkuehlmann/source/agentic-ventures/assets/customers/<kunde>/angebote/Angebot_<Kunde>_<Datum>.pdf

3. Validator-Output ernst nehmen

Der Validator gibt Errors (Build blockiert) und Warnings (Build laeuft, aber pruefen) aus.

Bei Rechnung blockiert immer:

  • Fehlende Steuernummer oder USt-IdNr (§ 14 Abs. 4 Nr. 2 UStG)
  • Fehlende fortlaufende Rechnungs-Nr (Nr. 4)
  • Fehlender Leistungszeitraum (Nr. 6)
  • Fehlende USt-Aufschluesselung (Nr. 8)
  • Fehlende IBAN (Beleg unbezahlbar)
  • Rechenfehler zwischen Positionen und Summe

Drei Beleg-Typen

typ: angebot

  • 4 Seiten Default (Cover → Leistungsumfang → Mehraufwand/Drittsysteme → Naechste Schritte)
  • Stack-Diagramm auf der Cover-Seite
  • Konditionen als hervorgehobene Preis-Cards
  • Optional: mehraufwand, drittsysteme, pills, stack, anlagen

Beispiel: beispiele/2026-05-21-angebot-woehrle.yaml

typ: rechnung

  • 1 Seite mit Positions-Tabelle + Summen-Block + Pflichtangaben-Footer
  • USt automatisch berechnet (oder Kleinunternehmer-Modus)
  • Validator prueft alle 8 Pflichtfelder aus § 14 UStG
  • Pflichtangaben-Footer (Anschrift, Vertretung, Register, Steuer, Bank) wird automatisch aus stammdaten.yaml gefuellt

typ: gutschrift

  • Wie Rechnung
  • Plus bezug_rechnung (Nummer + Datum + optional Grund) Pflicht
  • Betraege koennen negativ sein

Stripe-Look — wenn was anders aussehen soll

Templates: templates/_base.html.j2 (gemeinsame Styles) und templates/<typ>.html.j2.

Wenn du den Stripe-Look gegen z.B. AV-Brand-Lock (Dunkelgruen auf Creme) tauschen willst: nur die :root-CSS-Tokens in _base.html.j2 umstellen. Alle Templates ziehen sich das.

Tokens die du tauschen wuerdest:

  • --accent, --accent-deep, --accent-light, --accent-tint (aktuell Stripe Purple 533afd)
  • --surface (aktuell f6f9fc)
  • --ink (aktuell 061b31)

Schriften: --sans (aktuell Inter, fallback SF Pro Display).

GoBD-Konformitaet

Was die Skill abdeckt:

  • ✓ Vollstaendigkeit: Validator prueft alle Pflichtfelder aus § 14 UStG
  • ✓ Richtigkeit: rechnerische Konsistenz zwischen Positionen und Summen
  • ✓ Zeitgerechtheit: Rechnungsnummer fortlaufend per Vorlage (manueller Counter)
  • ✓ Ordnung: jeder Beleg liegt als YAML + HTML + PDF nebeneinander
  • ✓ Unveraenderbarkeit: YAML in git committen, PDF nie nachtraeglich aendern (bei Korrekturen → Gutschrift)

Was NICHT abgedeckt ist (manuell pruefen):

  • Aufbewahrungs-Pflicht 10 Jahre: Backup-Strategie fuer das Vault (S3-Bucket-Lock empfohlen)
  • Manuelle Korrekturen am PDF: nie machen. Bei Fehler: Gutschrift + neue Rechnung.
  • Rechnungs-Nummern-Eindeutigkeit: aktuell manuell. Wenn 50+ Rechnungen → counter.json einfuehren.

Beispiel-Workflow naechstes Mal

Marvin sagt: „schreib mir die Rechnung an Wöhrle für die Mai-Pauschale”.

  1. Skill triggert
  2. Ich nehme beispiele/<letzte-rechnung>.yaml als Vorlage
  3. Frage Marvin nur was sich aendert: Empfaenger, Positionen, Datum, Leistungszeitraum
  4. YAML schreiben, build, validator-Output zeigen
  5. Bei Errors: korrigieren. Bei Warnings: kurz erwaehnen.
  6. PDF oeffnen
  7. YAML in git commiten (GoBD-Nachvollziehbarkeit)

Files

  • SKILL.md — diese Datei
  • stammdaten.yaml — Source of Truth Absender + Recht + Bank
  • validator.py — deterministische Pflichtfeld-Checks
  • build.py — CLI (YAML → PDF)
  • templates/_base.html.j2 — gemeinsame Styles
  • templates/_macros.html.j2 — wiederverwendbare Bausteine (topbar, empfaenger, footer)
  • templates/angebot.html.j2 — 4-Seiten Angebots-Template
  • templates/rechnung.html.j2 — 1-Seiten Rechnungs-Template
  • templates/gutschrift.html.j2 — 1-Seiten Gutschrifts-Template
  • beispiele/2026-05-21-angebot-woehrle.yaml — erstes Live-Beispiel

Cross-Refs

Graphansicht