Best Practices für die Skill-Erstellung

## PDF-Text extrahieren

Verwenden Sie pdfplumber zur Textextraktion:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## PDF-Text extrahieren

PDF (Portable Document Format) Dateien sind ein gängiges Dateiformat, das
Text, Bilder und andere Inhalte enthält. Um Text aus einer PDF zu extrahieren, müssen Sie
eine Bibliothek verwenden. Es gibt viele Bibliotheken für die PDF-Verarbeitung, aber wir
empfehlen pdfplumber, da es einfach zu verwenden ist und die meisten Fälle gut handhabt.
Zunächst müssen Sie es mit pip installieren. Dann können Sie den folgenden Code verwenden...

## Code-Review-Prozess

1. Analysieren Sie die Codestruktur und Organisation
2. Überprüfen Sie auf potenzielle Fehler oder Grenzfälle
3. Schlagen Sie Verbesserungen für Lesbarkeit und Wartbarkeit vor
4. Überprüfen Sie die Einhaltung von Projektkonventionen

## Bericht generieren

Verwenden Sie diese Vorlage und passen Sie sie nach Bedarf an:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Daten verarbeiten
    # Ausgabe im angegebenen Format generieren
    # Optional Visualisierungen einschließen
```

## Datenbankmigrationen

Führen Sie genau dieses Skript aus:

```bash
python scripts/migrate.py --verify --backup
```

Ändern Sie den Befehl nicht und fügen Sie keine zusätzlichen Flags hinzu.

description: Extrahiert Text und Tabellen aus PDF-Dateien, füllt Formulare aus, führt Dokumente zusammen. Verwenden Sie, wenn Sie mit PDF-Dateien arbeiten oder wenn der Benutzer PDFs, Formulare oder Dokumentextraktion erwähnt.

description: Analysiert Excel-Tabellen, erstellt Pivot-Tabellen, generiert Diagramme. Verwenden Sie bei der Analyse von Excel-Dateien, Tabellen, tabellarischen Daten oder .xlsx-Dateien.

description: Generiert aussagekräftige Commit-Nachrichten durch Analyse von Git-Diffs. Verwenden Sie, wenn der Benutzer um Hilfe beim Schreiben von Commit-Nachrichten oder beim Überprüfen von bereitgestellten Änderungen bittet.

description: Hilft bei Dokumenten

description: Verarbeitet Daten

description: Macht Dinge mit Dateien

pdf/
├── SKILL.md              # Hauptanweisungen (geladen, wenn ausgelöst)
├── FORMS.md              # Formularausfüll-Leitfaden (bei Bedarf geladen)
├── reference.md          # API-Referenz (bei Bedarf geladen)
├── examples.md           # Verwendungsbeispiele (bei Bedarf geladen)
└── scripts/
    ├── analyze_form.py   # Utility-Skript (ausgeführt, nicht geladen)
    ├── fill_form.py      # Formularausfüll-Skript
    └── validate.py       # Validierungsskript

---
name: pdf-processing
description: Extrahiert Text und Tabellen aus PDF-Dateien, füllt Formulare aus und führt Dokumente zusammen. Verwenden Sie, wenn Sie mit PDF-Dateien arbeiten oder wenn der Benutzer PDFs, Formulare oder Dokumentextraktion erwähnt.
---

# PDF-Verarbeitung

## Schnellstart

Extrahieren Sie Text mit pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Erweiterte Funktionen

**Formularausfüllung**: Siehe [FORMS.md](FORMS.md) für vollständigen Leitfaden
**API-Referenz**: Siehe [REFERENCE.md](REFERENCE.md) für alle Methoden
**Beispiele**: Siehe [EXAMPLES.md](EXAMPLES.md) für häufige Muster

bigquery-skill/
├── SKILL.md (Übersicht und Navigation)
└── reference/
    ├── finance.md (Umsatz, ARR, Abrechnungsmetriken)
    ├── sales.md (Chancen, Pipeline)
    ├── product.md (API-Nutzung, Funktionen)
    └── marketing.md (Kampagnen, Attribution)

# DOCX-Verarbeitung

## Dokumente erstellen

Verwenden Sie docx-js für neue Dokumente. Siehe [DOCX-JS.md](DOCX-JS.md).

## Dokumente bearbeiten

Für einfache Bearbeitungen ändern Sie das XML direkt.

**Für nachverfolgte Änderungen**: Siehe [REDLINING.md](REDLINING.md)
**Für OOXML-Details**: Siehe [OOXML.md](OOXML.md)

# SKILL.md
Siehe [advanced.md](advanced.md)...

# advanced.md
Siehe [details.md](details.md)...

# details.md
Hier sind die eigentlichen Informationen...

# SKILL.md

**Grundlegende Nutzung**: [Anweisungen in SKILL.md]
**Erweiterte Funktionen**: Siehe [advanced.md](advanced.md)
**API-Referenz**: Siehe [reference.md](reference.md)
**Beispiele**: Siehe [examples.md](examples.md)

# API-Referenz

## Inhaltsverzeichnis
- Authentifizierung und Setup
- Kernmethoden (erstellen, lesen, aktualisieren, löschen)
- Erweiterte Funktionen (Batch-Operationen, Webhooks)
- Fehlerbehandlungsmuster
- Codebeispiele

## Authentifizierung und Setup
...

## Kernmethoden
...

## Forschungssynthese-Workflow

Kopieren Sie diese Checkliste und verfolgen Sie Ihren Fortschritt:

```
Forschungsfortschritt:
- [ ] Schritt 1: Alle Quelldokumente lesen
- [ ] Schritt 2: Schlüsselthemen identifizieren
- [ ] Schritt 3: Ansprüche kreuzen
- [ ] Schritt 4: Strukturierte Zusammenfassung erstellen
- [ ] Schritt 5: Zitate überprüfen
```

**Schritt 1: Alle Quelldokumente lesen**

Überprüfen Sie jedes Dokument im `sources/`-Verzeichnis. Notieren Sie die Hauptargumente und unterstützende Beweise.

**Schritt 2: Schlüsselthemen identifizieren**

Suchen Sie nach Mustern über Quellen hinweg. Welche Themen erscheinen wiederholt? Wo stimmen Quellen überein oder unterscheiden sich?

**Schritt 3: Ansprüche kreuzen**

Überprüfen Sie für jeden Hauptanspruch, dass er im Quellenmaterial erscheint. Notieren Sie, welche Quelle jeden Punkt unterstützt.

**Schritt 4: Strukturierte Zusammenfassung erstellen**

Organisieren Sie Erkenntnisse nach Thema. Fügen Sie ein:
- Hauptanspruch
- Unterstützende Beweise aus Quellen
- Widersprüchliche Standpunkte (falls vorhanden)

**Schritt 5: Zitate überprüfen**

Überprüfen Sie, dass jeder Anspruch auf das richtige Quelldokument verweist. Wenn Zitate unvollständig sind, kehren Sie zu Schritt 3 zurück.

## PDF-Formularausfüll-Workflow

Kopieren Sie diese Checkliste und haken Sie Elemente ab, während Sie sie abschließen:

```
Aufgabenfortschritt:
- [ ] Schritt 1: Formular analysieren (analyze_form.py ausführen)
- [ ] Schritt 2: Feldmapping erstellen (fields.json bearbeiten)
- [ ] Schritt 3: Mapping validieren (validate_fields.py ausführen)
- [ ] Schritt 4: Formular ausfüllen (fill_form.py ausführen)
- [ ] Schritt 5: Ausgabe überprüfen (verify_output.py ausführen)
```

**Schritt 1: Formular analysieren**

Führen Sie aus: `python scripts/analyze_form.py input.pdf`

Dies extrahiert Formularfelder und ihre Positionen und speichert sie in `fields.json`.

**Schritt 2: Feldmapping erstellen**

Bearbeiten Sie `fields.json`, um Werte für jedes Feld hinzuzufügen.

**Schritt 3: Mapping validieren**

Führen Sie aus: `python scripts/validate_fields.py fields.json`

Beheben Sie alle Validierungsfehler, bevor Sie fortfahren.

**Schritt 4: Formular ausfüllen**

Führen Sie aus: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Schritt 5: Ausgabe überprüfen**

Führen Sie aus: `python scripts/verify_output.py output.pdf`

Wenn die Überprüfung fehlschlägt, kehren Sie zu Schritt 2 zurück.

## Inhaltsüberprüfungsprozess

1. Entwerfen Sie Ihren Inhalt nach den Richtlinien in STYLE_GUIDE.md
2. Überprüfen Sie anhand der Checkliste:
   - Überprüfen Sie die Konsistenz der Terminologie
   - Überprüfen Sie, dass Beispiele dem Standardformat folgen
   - Bestätigen Sie, dass alle erforderlichen Abschnitte vorhanden sind
3. Wenn Probleme gefunden werden:
   - Notieren Sie jedes Problem mit spezifischem Abschnittsverweis
   - Überarbeiten Sie den Inhalt
   - Überprüfen Sie die Checkliste erneut
4. Fahren Sie nur fort, wenn alle Anforderungen erfüllt sind
5. Finalisieren und speichern Sie das Dokument

## Dokumentenbearbeitungsprozess

1. Nehmen Sie Ihre Änderungen an `word/document.xml` vor
2. **Validieren Sie sofort**: `python ooxml/scripts/validate.py unpacked_dir/`
3. Wenn die Validierung fehlschlägt:
   - Überprüfen Sie die Fehlermeldung sorgfältig
   - Beheben Sie die Probleme im XML
   - Führen Sie die Validierung erneut aus
4. **Fahren Sie nur fort, wenn die Validierung erfolgreich ist**
5. Neuaufbau: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Testen Sie das Ausgabedokument

Wenn Sie dies vor August 2025 tun, verwenden Sie die alte API.
Nach August 2025 verwenden Sie die neue API.

## Aktuelle Methode

Verwenden Sie den v2-API-Endpunkt: `api.example.com/v2/messages`

## Alte Muster

<details>
<summary>Legacy v1 API (veraltet 2025-08)</summary>

Die v1 API verwendete: `api.example.com/v1/messages`

Dieser Endpunkt wird nicht mehr unterstützt.
</details>

## Berichtsstruktur

VERWENDEN Sie IMMER diese genaue Vorlagenstruktur:

```markdown
# [Analysetitel]

## Zusammenfassung
[Ein-Absatz-Übersicht der Schlüsselergebnisse]

## Schlüsselergebnisse
- Ergebnis 1 mit unterstützenden Daten
- Ergebnis 2 mit unterstützenden Daten
- Ergebnis 3 mit unterstützenden Daten

## Empfehlungen
1. Spezifische umsetzbare Empfehlung
2. Spezifische umsetzbare Empfehlung
```

## Berichtsstruktur

Hier ist ein sinnvolles Standardformat, aber verwenden Sie Ihr bestes Urteilsvermögen basierend auf der Analyse:

```markdown
# [Analysetitel]

## Zusammenfassung
[Übersicht]

## Schlüsselergebnisse
[Passen Sie Abschnitte basierend auf Ihren Erkenntnissen an]

## Empfehlungen
[Passen Sie an den spezifischen Kontext an]
```

Passen Sie Abschnitte nach Bedarf für den spezifischen Analystyp an.

## Commit-Nachrichtenformat

Generieren Sie Commit-Nachrichten nach diesen Beispielen:

**Beispiel 1:**
Eingabe: Benutzerauthentifizierung mit JWT-Token hinzugefügt
Ausgabe:
```
feat(auth): JWT-basierte Authentifizierung implementieren

Login-Endpunkt und Token-Validierungs-Middleware hinzufügen
```

**Beispiel 2:**
Eingabe: Fehler behoben, bei dem Daten in Berichten falsch angezeigt wurden
Ausgabe:
```
fix(reports): Datumsformatierung in Zeitzonen-Konvertierung korrigieren

Verwenden Sie durchgehend UTC-Zeitstempel bei der Berichtsgenerierung
```

**Beispiel 3:**
Eingabe: Abhängigkeiten aktualisiert und Fehlerbehandlung umgestaltet
Ausgabe:
```
chore: Abhängigkeiten aktualisieren und Fehlerbehandlung umgestalten

- Upgrade lodash auf 4.17.21
- Standardisieren Sie das Fehlerantwortformat über Endpunkte
```

Folgen Sie diesem Stil: type(scope): kurze Beschreibung, dann detaillierte Erklärung.

## Dokumentänderungsworkflow

1. Bestimmen Sie den Änderungstyp:

   **Neuen Inhalt erstellen?** → Folgen Sie dem Abschnitt „Erstellungs-Workflow" unten
   **Vorhandenen Inhalt bearbeiten?** → Folgen Sie dem Abschnitt „Bearbeitungs-Workflow" unten

2. Erstellungs-Workflow:
   - Verwenden Sie die docx-js-Bibliothek
   - Erstellen Sie das Dokument von Grund auf
   - Exportieren Sie in das .docx-Format

3. Bearbeitungs-Workflow:
   - Entpacken Sie das vorhandene Dokument
   - Ändern Sie das XML direkt
   - Validieren Sie nach jeder Änderung
   - Packen Sie erneut, wenn fertig

{
  "skills": ["pdf-processing"],
  "query": "Extrahieren Sie den gesamten Text aus dieser PDF-Datei und speichern Sie ihn in output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Liest die PDF-Datei erfolgreich mit einer geeigneten PDF-Verarbeitungsbibliothek oder einem Befehlszeilentool",
    "Extrahiert Textinhalte aus allen Seiten im Dokument ohne Seiten zu überspringen",
    "Speichert den extrahierten Text in einer Datei namens output.txt in einem klaren, lesbaren Format"
  ]
}

**Schlechtes Beispiel: Zu viele Wahlmöglichkeiten** (verwirrend):
„Sie können pypdf verwenden, oder pdfplumber, oder PyMuPDF, oder pdf2image, oder..."

**Gutes Beispiel: Geben Sie einen Standard an** (mit Fluchtweg):
„Verwenden Sie pdfplumber zur Textextraktion:
```python
import pdfplumber
```

Für gescannte PDFs, die OCR erfordern, verwenden Sie stattdessen pdf2image mit pytesseract."

def process_file(path):
    """Verarbeiten Sie eine Datei und erstellen Sie sie, falls sie nicht existiert."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Erstellen Sie die Datei mit Standardinhalt, anstatt zu fehlschlagen
        print(f"Datei {path} nicht gefunden, erstelle Standard")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Geben Sie eine Alternative an, anstatt zu fehlschlagen
        print(f"Kann nicht auf {path} zugreifen, verwende Standard")
        return ''

def process_file(path):
    # Fehlschlag einfach und lassen Sie Claude es herausfinden
    return open(path).read()

# HTTP-Anfragen werden normalerweise innerhalb von 30 Sekunden abgeschlossen
# Längeres Timeout berücksichtigt langsame Verbindungen
REQUEST_TIMEOUT = 30

# Drei Versuche balancieren Zuverlässigkeit vs. Geschwindigkeit
# Die meisten intermittierenden Fehler werden beim zweiten Versuch behoben
MAX_RETRIES = 3

TIMEOUT = 47  # Warum 47?
RETRIES = 5   # Warum 5?

## Utility-Skripte

**analyze_form.py**: Extrahieren Sie alle Formularfelder aus PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Ausgabeformat:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Überprüfen Sie auf überlappende Begrenzungsrahmen

```bash
python scripts/validate_boxes.py fields.json
# Gibt zurück: „OK" oder listet Konflikte auf
```

**fill_form.py**: Wenden Sie Feldwerte auf PDF an

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

## Formular-Layout-Analyse

1. Konvertieren Sie PDF in Bilder:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analysieren Sie jedes Seitenbild, um Formularfelder zu identifizieren
3. Claude kann Feldpositionen und -typen visuell sehen

bigquery-skill/
├── SKILL.md (Übersicht, verweist auf Referenzdateien)
└── reference/
    ├── finance.md (Umsatzmetriken)
    ├── sales.md (Pipeline-Daten)
    └── product.md (Nutzungsanalysen)

Verwenden Sie das BigQuery:bigquery_schema Tool, um Tabellenschemas abzurufen.
Verwenden Sie das GitHub:create_issue Tool, um Probleme zu erstellen.

**Schlechtes Beispiel: Nimmt Installation an**:
„Verwenden Sie die pdf-Bibliothek, um die Datei zu verarbeiten."

**Gutes Beispiel: Explizit über Abhängigkeiten**:
„Installieren Sie erforderliches Paket: `pip install pypdf`

Verwenden Sie es dann:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"