Geschaeftsbrief Skill (DIN 5008 + optionaler LetterXpress-Versand)

Dieses Skill erzeugt DIN 5008-konforme Geschaeftsbriefe als PDF. Optional koennen Briefe ueber die LetterXpress API versendet werden (im Testmodus, d.h. keine Kosten, keine echten Briefe).

Umgebung einrichten

Bevor die eigentlichen Scripts ausfuehrbar sind, muss eine virtuelle Umgebung mit allen Abhaengigkeiten eingerichtet werden. Dafuer nutzt der Skill uv — einen schnellen Python-Paketmanager. Das Setup-Script erledigt alles automatisch:

python3 SKILL_DIR/scripts/setup_env.py

Das erstellt eine .venv im Skill-Verzeichnis und installiert reportlab und alle weiteren Abhaengigkeiten aus requirements.txt. Danach werden alle Scripts mit dem Python aus der venv aufgerufen:

SKILL_DIR/.venv/bin/python3 SKILL_DIR/scripts/create_din5008_letter.py ...

Falls uv noch nicht installiert ist, installiere es zuerst:

pip install uv --break-system-packages

Das Setup muss nur einmal pro Umgebung laufen. Falls die .venv bereits existiert, prueft das Script ob alles aktuell ist und ueberspringt die Erstellung.

Ablauf

Der Workflow besteht aus vier Schritten:

1. Briefdaten sammeln — Absender, Empfaenger, Betreff, Inhalt
2. Quality-Gate: Pre-Validation — Daten pruefen bevor das PDF erzeugt wird
3. DIN 5008 PDF erzeugen — mit dem Script scripts/create_din5008_letter.py
4. User fragen: Versand gewuenscht? — Falls ja: Post-Validation + LetterXpress-Versand

Nach der PDF-Erstellung ist der Brief fertig. Frage den Benutzer explizit: “Soll der Brief ueber LetterXpress versendet werden?” Nur wenn der Benutzer zustimmt, fahre mit Schritt 4 (Validation + Versand) fort. Andernfalls ist der Workflow nach Schritt 3 abgeschlossen.

Das Quality-Gate (scripts/validate_letter.py) ist ein automatischer Test, der sicherstellt, dass Absender und Empfaenger korrekt im Sichtfenster eines DIN-Fensterbriefumschlags positioniert sind. Kein Brief wird versendet, bevor das Quality-Gate bestanden ist.

Schritt 1: Briefdaten sammeln

Frage den Benutzer nach folgenden Informationen (soweit nicht bereits bekannt):

Absender:

• Name / Firma
• Strasse und Hausnummer
• PLZ und Ort
• Optional: Telefon, E-Mail, Website

Empfaenger:

• Name / Firma
• Optional: Zusatzzeile (z.B. “z.Hd. Frau Mueller”)
• Strasse und Hausnummer
• PLZ und Ort
• Land (falls nicht Deutschland)

Brief:

• Betreff (kurz und praegnant)
• Brieftext (der eigentliche Inhalt)
• Ort und Datum (Standard: heute)
• Grussformel (Standard: “Mit freundlichen Gruessen”)
• Unterschrift-Name

Wenn der Benutzer nur sagt “schreibe einen Brief an X wegen Y”, formuliere den Brieftext selbst in einem professionellen, hoeflichen Geschaeftsdeutsch. Zeige dem Benutzer den entworfenen Text und frage, ob er passt, bevor du das PDF erzeugst.

Schritt 2: Quality-Gate Pre-Validation

Bevor das PDF erzeugt wird, pruefe die Briefdaten mit dem Validierungsscript. Das verhindert, dass ein fehlerhaftes PDF erzeugt und versendet wird.

python3 SKILL_DIR/scripts/validate_letter.py --letter /path/to/brief.md --strict

Das Script prueft:

• Alle Pflichtfelder vorhanden (Absender: Name, Strasse, PLZ, Ort; Empfaenger ebenso)
• PLZ-Format korrekt (5 Ziffern fuer deutsche Adressen)
• Ruecksendeangabe passt in die Breite des Briefumschlag-Fensters (max. 90 Zeichen)
• Empfaengeranschrift hat maximal 6 Zeilen (DIN 5008 Vorgabe)
• Einzelne Adresszeilen passen in die Fensterbreite (max. ~55 Zeichen bei 11pt)
• Betreff und Brieftext vorhanden
• Anrede beginnt mit “Sehr geehrt…” oder “Liebe…”
• Grussformel vorhanden

Wichtig: Nur wenn das Script Exit-Code 0 liefert (alle Pruefungen bestanden), darf mit der PDF-Erstellung fortgefahren werden. Bei Fehlern muessen die Daten korrigiert werden.

Schritt 3: DIN 5008 PDF erzeugen

Lies die DIN 5008 Spezifikation in references/din5008_spec.md fuer Details zu den exakten Massen. Das Script scripts/create_din5008_letter.py setzt diese Spezifikation vollstaendig um (Form B).

Erstelle eine Markdown-Datei mit YAML-Frontmatter:

---
sender_name: Max Mustermann GmbH
sender_street: Musterstrasse 1
sender_zip: "80331"
sender_city: Muenchen
sender_phone: "+49 89 123456"
sender_email: info@mustermann.de
sender_website: www.mustermann.de
recipient_name: Erika Beispiel AG
recipient_additional: z.Hd. Frau Mueller
recipient_street: Beispielweg 42
recipient_zip: "10115"
recipient_city: Berlin
recipient_country: ""
subject: Angebot Nr. 2024-001
date: 16. Februar 2026
location: Muenchen
closing: Mit freundlichen Gruessen
signature_name: Max Mustermann
briefpapier: /pfad/zum/briefpapier.pdf
---

Sehr geehrte Frau Mueller,

hiermit uebersenden wir Ihnen...

Der Brieftext folgt hier nach dem Frontmatter.

Dann rufe das Script auf:

SKILL_DIR/.venv/bin/python3 SKILL_DIR/scripts/create_din5008_letter.py \
  --output /path/to/brief.pdf \
  --letter /path/to/brief.md

Ersetze SKILL_DIR durch den tatsaechlichen Pfad zum Skill-Verzeichnis.

Schritt 4 (optional): Post-Validation und LetterXpress-Versand

Dieser Schritt wird nur ausgefuehrt, wenn der Benutzer den Versand wuenscht.

4a: PDF validieren (Quality-Gate)

Nach der PDF-Erstellung wird das PDF nochmals geprueft. Falls pdfminer.six oder PyMuPDF installiert ist, werden die tatsaechlichen Textpositionen im PDF analysiert. Andernfalls reicht die Pre-Validation aus Schritt 2.

python3 SKILL_DIR/scripts/validate_letter.py \
  --letter /path/to/brief.md \
  --pdf /path/to/brief.pdf \
  --strict

Nur bei Exit-Code 0 darf versendet werden.

4b: An LetterXpress senden

Nutze scripts/send_letterxpress.py. Es arbeitet immer im Testmodus.

Credentials: Das Script liest Credentials automatisch aus der macOS Keychain (Services: letterxpress-username und letterxpress-apikey). Falls nicht in der Keychain vorhanden, frage den Benutzer und speichere sie:

security add-generic-password -s "letterxpress-username" -a "USER" -w "BENUTZERNAME" -U
security add-generic-password -s "letterxpress-apikey" -a "USER" -w "API_KEY" -U

Versand (Credentials werden aus Keychain gelesen):

python3 SKILL_DIR/scripts/send_letterxpress.py \
  --pdf /path/to/brief.pdf

Alternativ koennen Credentials auch direkt uebergeben werden:

python3 SKILL_DIR/scripts/send_letterxpress.py \
  --pdf /path/to/brief.pdf \
  --username "BENUTZERNAME" \
  --apikey "API_KEY"

Versand-Optionen

Das Script gibt die Job-ID und den Status zurueck.

Fehlerbehandlung

• Bei Quality-Gate-Fehlern: zeige die fehlgeschlagenen Pruefungen und schlage Korrekturen vor
• Bei API-Fehlern: zeige die Fehlermeldung und schlage Loesungen vor
• Bei Netzwerkproblemen: schlage vor, es erneut zu versuchen
• Bei fehlenden Credentials: frage den Benutzer erneut
• Wenn das PDF zu gross ist (max. 50 Seiten): informiere den Benutzer

Briefpapier (optionales Overlay)

Im Frontmatter kann eine PDF-Datei als Briefpapier angegeben werden:

briefpapier: /pfad/zum/briefpapier.pdf

Das Briefpapier wird als Hintergrund-Layer unter den Brief gelegt:

• Seite 1 des Briefpapiers -> unter Seite 1 des Briefs
• Seite 2 des Briefpapiers (falls vorhanden) -> unter alle Folgeseiten
• Hat das Briefpapier nur 1 Seite, wird diese fuer alle Seiten verwendet

Das Briefpapier-PDF muss DIN A4 Hochformat sein. Typisch enthaelt es Logo, Kopfzeile, Fusszeile und Gestaltungselemente. Der Briefinhalt wird transparent darueber gelegt — das Briefpapier darf keine Inhalte in den Textbereichen haben.

Hinweis: Bei Verwendung von Briefpapier werden Absender-Header und Falzmarken trotzdem gezeichnet. Falls das Briefpapier diese bereits enthaelt, sollten die entsprechenden Felder im Frontmatter leer gelassen oder das Briefpapier entsprechend gestaltet werden.

Wichtige Hinweise

• Testmodus ist immer aktiv — keine echten Briefe, keine Kosten
• Quality-Gate ist Pflicht — kein Versand ohne bestandene Validierung
• Das PDF muss DIN A4 Hochformat sein
• Falzmarken und Lochmarke werden automatisch gesetzt
• Die Absenderzeile im Anschriftfeld ist in kleiner Schrift (6pt, unterstrichen)
• Der Brieftext nutzt 11pt Helvetica
• Das Briefumschlag-Sichtfenster liegt bei X: 20-110mm, Y: 45-90mm vom oberen Rand
• Empfaengeradresse beginnt bei 66mm vom oberen Rand (nicht 62.7mm), damit der LetterXpress Einschreiben-Banner (17mm hoch) immer Platz hat — auch bei nachtraeglicher Entscheidung fuer Einschreiben-Versand