Best Practices

Gute Skills sind prägnant, klar strukturiert und mit echter Nutzung getestet. Dieser Leitfaden bietet praktische Entscheidungen für das Schreiben von Skills, die Claude zuverlässig finden und effektiv einsetzen kann.

Konzeptionellen Hintergrund findest du im Skills-Überblick.

Grundprinzipien

Prägnanz ist entscheidend

Das Kontextfenster ist eine gemeinsame Ressource. Deine Skill teilt dieses Fenster mit allem anderen, was Claude wissen muss: Systemprompt, Gesprächsverlauf, Metadaten anderer Skills und die eigentliche Anfrage.

Nicht jeder Token in deiner Skill hat sofort Kosten. Beim Start werden nur die Metadaten (name und description) aller Skills vorgeladen. Claude liest SKILL.md erst, wenn die Skill relevant wird, und weitere Dateien nur bei Bedarf. Trotzdem zählt Prägnanz: Sobald SKILL.md geladen ist, konkurriert jeder Token mit Gesprächsverlauf und anderem Kontext.

Standardannahme: Claude ist bereits sehr intelligent.

Füge nur Kontext hinzu, den Claude nicht schon hat. Prüfe jede Information:

• "Braucht Claude diese Erklärung wirklich?"
• "Kann ich annehmen, dass Claude das weiß?"
• "Rechtfertigt dieser Absatz seine Token-Kosten?"

Gutes Beispiel: prägnant:

## Extract PDF text

Use pdfplumber for text extraction:
```python
import pdfplumber

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

Schlechtes Beispiel: zu ausführlich:

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

Die kurze Fassung setzt voraus, dass Claude weiß, was PDFs sind und wie Bibliotheken funktionieren.

Geeignete Freiheitsgrade setzen

Passe die Genauigkeit an Fragilität und Variabilität der Aufgabe an.

Hohe Freiheit passt, wenn mehrere Ansätze gültig sind, Entscheidungen vom Kontext abhängen und Heuristiken die Richtung vorgeben.

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

Mittlere Freiheit passt, wenn ein bevorzugtes Muster existiert, etwas Variation akzeptabel ist und Konfiguration das Verhalten beeinflusst.

## Generate report

Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
```

Niedrige Freiheit passt, wenn Abläufe fragil und fehleranfällig sind, Konsistenz kritisch ist oder eine genaue Sequenz eingehalten werden muss.

## Database migration

Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.

Stell dir Claude als Roboter vor, der einen Weg erkundet. Auf einer schmalen Brücke mit Abgründen braucht er exakte Anweisungen. Auf einer offenen Wiese ohne Gefahr reicht eine Richtung.

Mit allen geplanten Modellen testen

Skills wirken als Ergänzungen zu Modellen; die Wirksamkeit hängt daher vom zugrunde liegenden Modell ab. Teste mit allen Modellen, die du einsetzen willst.

• Claude Haiku: Bietet die Skill genug Anleitung?
• Claude Sonnet: Ist die Skill klar und effizient?
• Claude Opus: Vermeidet sie Übererklärung?

Was mit Opus perfekt funktioniert, braucht für Haiku möglicherweise mehr Details. Für mehrere Modelle sollten die Anweisungen mit allen gut funktionieren.

Skill-Struktur

Namenskonventionen

Nutze konsistente Namen, damit Skills leicht referenziert und besprochen werden können. Wir empfehlen die englische -ing-Form, weil sie Aktivität oder Fähigkeit klar beschreibt.

Gute Beispiele: "Processing PDFs", "Analyzing spreadsheets", "Managing databases", "Testing code", "Writing documentation".

Akzeptable Alternativen: Nominalphrasen wie "PDF Processing" oder aktionsorientierte Namen wie "Process PDFs".

Vermeiden: vage Namen wie "Helper", "Utils", "Tools"; zu generische Namen wie "Documents", "Data", "Files"; uneinheitliche Muster in der Sammlung.

Konsistente Namen erleichtern Dokumentation, Suche, Organisation und eine professionelle Skill-Bibliothek.

Wirksame Beschreibungen schreiben

Das Feld description ermöglicht Skill-Erkennung und sollte enthalten, was die Skill tut und wann sie verwendet werden soll.

Sei konkret und nenne Schlüsselbegriffe. Claude nutzt die Beschreibung, um aus potenziell mehr als 100 Skills die passende auszuwählen. Implementierungsdetails gehören in den Rest von SKILL.md.

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Vermeide vage Beschreibungen:

description: Helps with documents

description: Processes data

description: Does stuff with files

Muster für progressive Offenlegung

SKILL.md dient als Überblick und verweist Claude bei Bedarf auf detaillierte Materialien, wie ein Inhaltsverzeichnis in einem Onboarding-Leitfaden. Details findest du unter Wie Skills funktionieren.

Praktische Hinweise:

• SKILL.md unter 500 Zeilen halten
• Bei Annäherung an diese Grenze Inhalte in separate Dateien auslagern
• Die folgenden Muster für Anweisungen, Code und Ressourcen nutzen

Eine einfache Skill beginnt mit nur einer SKILL.md mit Metadaten und Anweisungen.

Wenn sie wächst, kannst du zusätzliche Inhalte bündeln, die Claude nur bei Bedarf lädt.

pdf/
|-- SKILL.md
|-- FORMS.md
|-- reference.md
|-- examples.md
`-- scripts/
  |-- analyze_form.py
  |-- fill_form.py
  `-- validate.py

Muster 1: Überblick mit Referenzen

---
name: PDF Processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

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

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude lädt diese Dateien nur bei Bedarf.

Muster 2: Organisation nach Domäne

Bei Skills mit mehreren Domänen vermeidet Domänenorganisation unnötigen Kontext. Für sales metrics braucht Claude sales-Schemata, nicht finance oder marketing.

bigquery-skill/
|-- SKILL.md (overview and navigation)
`-- reference/
  |-- finance.md (revenue, billing metrics)
  |-- sales.md (opportunities, pipeline)
  |-- product.md (API usage, features)
  `-- marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing -> See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts -> See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption -> See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email -> See [reference/marketing.md](reference/marketing.md)

Muster 3: Bedingte Details

Zeige Basisinhalte und verlinke fortgeschrittene Inhalte.

# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude liest REDLINING.md oder OOXML.md nur, wenn diese Funktionen gebraucht werden.

Tief verschachtelte Referenzen vermeiden

Claude liest Dateien, die aus anderen Referenzdateien heraus verlinkt sind, möglicherweise nur teilweise. Halte Referenzen daher eine Ebene tief ab SKILL.md und verlinke wichtige Dateien direkt.

# Schlecht
SKILL.md -> advanced.md -> details.md

# Gut
SKILL.md verlinkt advanced.md, reference.md und examples.md direkt

Lange Referenzdateien mit Inhaltsverzeichnis strukturieren

Für Referenzdateien über 100 Zeilen sollte oben ein Inhaltsverzeichnis stehen, damit Claude auch bei Teillesen den Umfang erkennt.

Workflows und Feedback-Schleifen

Workflows für komplexe Aufgaben verwenden

Zerlege komplexe Abläufe in klare Schritte. Für besonders komplexe Workflows kannst du eine Checkliste bereitstellen, die Claude kopieren und abhaken kann.

## Research synthesis workflow

Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations

Dasselbe Muster funktioniert für Code-Workflows:

## PDF form filling workflow

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

Klare Schritte verhindern, dass Claude kritische Validierung überspringt.

Feedback-Schleifen implementieren

Häufiges Muster: Validator ausführen -> Fehler beheben -> wiederholen.

Bei Skills ohne Code kann STYLE_GUIDE.md als Validator dienen. Claude liest ihn und vergleicht. Bei Skills mit Code wird nach jeder Änderung validiert und erst bei bestandener Prüfung fortgefahren.

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails, fix XML and validate again
4. **Only proceed when validation passes**
5. Rebuild and test the output document

Inhaltsrichtlinien

Zeitabhängige Informationen vermeiden

Nimm keine Informationen auf, die bald veralten. Verwende eine aktuelle Methode und lagere alte Muster in einen separaten Abschnitt aus.

## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>

Konsistente Terminologie verwenden

Wähle einen Begriff und verwende ihn durchgehend. Verwende immer "API endpoint", "field" und "extract"; mische nicht unnötig "URL", "route", "path", "box", "element", "pull" oder "retrieve". Konsistenz hilft Claude, Anweisungen zu verstehen und zu befolgen.

Häufige Muster

Vorlagenmuster

Stelle Vorlagen für Ausgabeformate bereit und passe ihre Strenge an die Anforderungen an.

## Report structure

ALWAYS use this exact template structure:
```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```

Wenn Anpassung nützlich ist, gib ein sinnvolles Standardformat und erlaube Claude, Abschnitte an den Kontext anzupassen.

Beispielmuster

Wenn Qualität vom Sehen von Beispielen abhängt, gib Eingabe/Ausgabe-Paare an.

## Commit message format

Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

Beispiele zeigen Stil und Detailgrad klarer als Beschreibungen allein.

Bedingtes Workflow-Muster

Führe Claude durch Entscheidungspunkte.

## Document modification workflow

1. Determine the modification type:
 **Creating new content?** -> Follow "Creation workflow" below
 **Editing existing content?** -> Follow "Editing workflow" below

2. Creation workflow:
 - Use docx-js library
 - Build document from scratch
 - Export to .docx format

3. Editing workflow:
 - Unpack existing document
 - Modify XML directly
 - Validate after each change
 - Repack when complete

Evaluation und Iteration

Evaluationen zuerst erstellen

Erstelle Evaluationen, bevor du umfangreiche Dokumentation schreibst. So stellst du sicher, dass die Skill echte Probleme löst.

1. Führe Claude ohne Skill auf repräsentativen Aufgaben aus und dokumentiere Lücken
2. Erstelle drei Szenarien für diese Lücken
3. Messe die Baseline ohne Skill
4. Schreibe minimale Anweisungen
5. Führe Evaluationen aus, vergleiche und verfeinere

{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
  "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
  "Extracts text content from all pages in the document without missing any pages",
  "Saves the extracted text to a file named output.txt in a clear, readable format"
]
}

Skills iterativ mit Claude entwickeln

Arbeite mit einer Instanz ("Claude A"), um eine Skill zu erstellen, die andere Instanzen ("Claude B") verwenden. Claude A hilft beim Entwerfen und Verfeinern, Claude B testet in echten Aufgaben. Löse zuerst eine Aufgabe ohne Skill, beobachte wiederholten Kontext und Regeln, lasse Claude A daraus eine Skill machen und teste mit Claude B. Wenn Claude B eine Regel vergisst oder eine Information nicht findet, bringe die konkrete Beobachtung zurück zu Claude A und verbessere.

Für bestehende Skills wechselst du zwischen Verbesserung mit Claude A, Test mit Claude B und Beobachtung des Verhaltens. Sammle Teamfeedback zu Aktivierung, Klarheit und fehlenden Inhalten.

Beobachten, wie Claude Skills navigiert

Achte auf unerwartete Dateireihenfolgen, nicht verfolgte Referenzen, Überabhängigkeit von bestimmten Dateien und nie genutzte Inhalte. Iteriere anhand dieser Beobachtungen. name und description sind besonders wichtig für die Entscheidung, ob eine Skill ausgelöst wird.

Zu vermeidende Antimuster

Windows-Pfade vermeiden

Verwende immer normale Schrägstriche.

• Gut: scripts/helper.py, reference/guide.md
• Vermeiden: scripts\helper.py, reference\guide.md

Nicht zu viele Optionen anbieten

Zeige nicht mehrere Ansätze, wenn es nicht nötig ist.

**Bad example: Too many choices**:
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default**:
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

Fortgeschritten: Skills mit ausführbarem Code

Diese Abschnitte betreffen Skills mit ausführbaren Skripten. Wenn deine Skill nur Markdown-Anweisungen nutzt, springe zur Checkliste.

Lösen, nicht abwälzen

Skripte sollten Fehlerfälle behandeln, statt sie Claude zu überlassen.

def process_file(path):
  """Process a file, creating it if it doesn't exist."""
  try:
      with open(path) as f:
          return f.read()
  except FileNotFoundError:
      print(f"File {path} not found, creating default")
      with open(path, 'w') as f:
          f.write('')
      return ''
  except PermissionError:
      print(f"Cannot access {path}, using default")
      return ''

Dokumentiere auch Konfigurationswerte, damit keine "voodoo constants" entstehen.

# HTTP requests typically complete within 30 seconds
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
MAX_RETRIES = 3

Hilfsskripte bereitstellen

Vorgefertigte Skripte sind zuverlässiger als generierter Code, sparen Tokens und Zeit und sichern Konsistenz.

Mach klar, ob Claude das Skript ausführen oder als Referenz lesen soll.

## Utility scripts

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

**validate_boxes.py**:
```bash
python scripts/validate_boxes.py fields.json
```

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

Visuelle Analyse verwenden

Wenn Eingaben als Bilder gerendert werden können, lasse Claude sie visuell analysieren.

## Form layout analysis

1. Convert PDF to images:
```bash
   python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields

Überprüfbare Zwischenausgaben erstellen

Für komplexe Aufgaben eignet sich "plan-validate-execute": Claude erstellt erst einen strukturierten Plan, ein Skript validiert ihn, und erst dann wird ausgeführt. Das fängt Fehler früh ab, ermöglicht objektive Prüfung, schützt Originale und macht Debugging klarer.

Abhängigkeiten paketieren

• claude.ai kann Pakete aus npm und PyPI installieren und GitHub-Repositories abrufen
• Anthropic API hat keinen Netzwerkzugriff und keine Paketinstallation zur Laufzeit

Liste benötigte Pakete in SKILL.md und prüfe Verfügbarkeit in der Dokumentation zum Code-Ausführungstool.

Laufzeitumgebung

Skills laufen mit Dateisystem, bash und Codeausführung. Metadaten werden vorgeladen; Dateien werden bei Bedarf gelesen; Skripte laufen, ohne ihren ganzen Inhalt in den Kontext zu laden; große Dateien kosten nichts, bis sie gelesen werden. Nutze /-Pfade, sprechende Dateinamen, Domänenorganisation und Skripte für deterministische Operationen.

MCP-Tool-Referenzen

Nutze vollständig qualifizierte Namen.

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Nicht annehmen, dass Tools installiert sind

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```

Technische Hinweise

YAML-Frontmatter-Anforderungen

SKILL.md enthält nur name und description. Siehe Skills-Überblick.

Token-Budgets

Halte SKILL.md unter 500 Zeilen. Wenn mehr nötig ist, teile Inhalte mit progressiver Offenlegung in separate Dateien auf.

Checkliste für wirksame Skills

Kernqualität

• Beschreibung ist konkret und enthält Schlüsselbegriffe
• Beschreibung enthält Funktion und Einsatzzeitpunkt
• SKILL.md ist unter 500 Zeilen
• Zusätzliche Details liegen bei Bedarf in separaten Dateien
• Keine zeitabhängigen Informationen, oder Abschnitt "old patterns"
• Terminologie ist konsistent
• Beispiele sind konkret
• Dateireferenzen sind eine Ebene tief
• Progressive Offenlegung wird passend genutzt
• Workflows haben klare Schritte

Code und Skripte

• Skripte lösen Probleme, statt an Claude abzuwälzen
• Fehlerbehandlung ist explizit und hilfreich
• Keine "voodoo constants"
• Erforderliche Pakete sind gelistet und geprüft
• Skripte sind klar dokumentiert
• Keine Windows-Pfade
• Validierungsschritte für kritische Operationen
• Feedback-Schleifen für qualitätskritische Aufgaben

Tests

• Mindestens drei Evaluationen erstellt
• Mit Haiku, Sonnet und Opus getestet
• Mit echten Nutzungsszenarien getestet
• Teamfeedback eingearbeitet, falls relevant

Nächste Schritte