Claude Skills und SKILL.md: Wie modulare Fähigkeiten KI-Agenten transformieren

Claude Code und der Claude Agent SDK haben mit dem Skills-System einen Paradigmenwechsel eingeführt: Statt alle Anweisungen in eine monolithische Konfigurationsdatei zu packen, werden Fähigkeiten modular als einzelne Skill-Einheiten definiert. Das zentrale Element dabei ist die SKILL.md – ein Manifest, das beschreibt, was ein Skill kann, wann er aktiviert werden soll und welche Ressourcen dazugehören.

Das Problem: Context-Window-Grenzen

Jedes KI-Modell hat ein begrenztes Kontextfenster. Selbst bei 200.000 Tokens (wie bei Claude 3) wird es eng, wenn dutzende Skill-Definitionen, umfangreiche Codebasen und Konversationshistorie zusammenkommen.

Das klassische Dilemma:

Viele Fähigkeiten = großer Prompt = weniger Platz für eigentliche Arbeit
Wenige Fähigkeiten = beschränkte Einsatzmöglichkeiten

Anthropics Lösung: Progressive Disclosure. Skills werden erst dann vollständig geladen, wenn sie tatsächlich benötigt werden. Beim Start einer Session sieht Claude nur Name und Beschreibung jedes installierten Skills – das sind pro Skill etwa 30-50 Tokens. Der vollständige Inhalt wird erst bei Aktivierung nachgeladen.

Was ist eine SKILL.md?

Die SKILL.md ist das zentrale Manifest einer Skill-Einheit. Sie besteht aus zwei Teilen:

1. YAML-Frontmatter (Metadaten)

---
name: seo-content-writer
description: >
  Erstellt SEO-optimierte deutsche Artikel mit korrekter
  Keyword-Dichte und HTML-Struktur. Wird aktiviert, wenn ein Benutzer
  auf die Erstellung von SEO-Texten oder Website-Content abzielt.
---

Die description ist entscheidend: Claude entscheidet anhand dieser Beschreibung, ob der Skill für eine Anfrage relevant ist. Sie sollte:

Aus Claudes Perspektive formuliert sein
Klare Trigger-Bedingungen nennen (“wird aktiviert, wenn…”)
Die Kernfähigkeiten benennen

2. Markdown-Inhalt (Instruktionen)

Unter dem Frontmatter folgt der eigentliche Prompt – strukturiert in Sektionen wie:

Übersicht: Was der Skill macht
Voraussetzungen: Was vorhanden sein muss
Ausführung: Schritt-für-Schritt-Anleitung
Beispiele: Konkrete Input/Output-Paare
Einschränkungen: Was der Skill nicht tut

Der Lade-Mechanismus im Detail

Der Mechanismus funktioniert dreistufig:

Stufe 1: Discovery (Session-Start)

Beim Start lädt Claude nur die Metadaten aller installierten Skills:

Verfügbare Skills:
- seo-content-writer: Erstellt SEO-optimierte Artikel...
- data-privacy-checker: Prüft DSGVO-Konformität...
- code-reviewer: Analysiert Code auf Best Practices...

Das kostet minimal Tokens, gibt Claude aber einen Überblick über verfügbare Fähigkeiten.

Stufe 2: Matching (Bei Anfrage)

Wenn der User eine Anfrage stellt, gleicht Claude die Beschreibungen ab:

User: “Schreibe einen SEO-optimierten Artikel über Cloud Computing”

Claude (intern): Beschreibung von seo-content-writer passt → Skill aktivieren

Stufe 3: Vollständiges Laden

Erst jetzt wird der komplette Inhalt der SKILL.md geladen, inklusive:

Aller Instruktionen
Referenzierter Ressourcen aus Unterordnern
Verlinkter Templates und Beispiele

Aufbau einer effektiven SKILL.md

Minimales Beispiel

---
name: data-privacy-checker
description: >
  Prüft Text oder Dokumente auf DSGVO-konforme Formulierungen und warnt
  bei Verstößen. Aktiviert bei Anfragen zur Daten- und Datenschutzprüfung.
---

# Datenschutz-Prüfung

## Instruktionen

1. Analysiere den bereitgestellten Text auf personenbezogene Daten
2. Prüfe Formulierungen auf DSGVO-Konformität
3. Identifiziere fehlende Einwilligungserklärungen
4. Erstelle einen Prüfbericht mit konkreten Handlungsempfehlungen

## Prüfkriterien

- Transparenzpflichten (Art. 13/14 DSGVO)
- Rechtsgrundlagen für Verarbeitung (Art. 6 DSGVO)
- Einwilligungsformulierungen (Art. 7 DSGVO)
- Betroffenenrechte (Art. 15-22 DSGVO)

## Output-Format

Erstelle einen strukturierten Bericht mit:
- Zusammenfassung (1-2 Sätze)
- Gefundene Probleme (priorisiert nach Schwere)
- Konkrete Änderungsvorschläge
- Checkliste für Nachbesserung

Erweiterte Struktur mit Ressourcen

Komplexere Skills können zusätzliche Dateien referenzieren:

skills/
└── code-review/
    ├── SKILL.md
    ├── resources/
    │   ├── style-guide.md
    │   └── security-checklist.md
    ├── references/
    │   └── owasp-top-10.md
    └── scripts/
        └── lint-config.json

In der SKILL.md wird dann referenziert:

## Ressourcen

- Stilrichtlinien: siehe `resources/style-guide.md`
- Sicherheitsprüfung: verwende `resources/security-checklist.md`
- OWASP-Referenz: bei Sicherheitsfragen konsultiere `references/owasp-top-10.md`

Diese Dateien werden erst geladen, wenn die SKILL.md sie explizit referenziert.

Optionale Frontmatter-Felder

Neben den erforderlichen name und description gibt es weitere nützliche Felder:

---
name: seo-content-writer
description: >
  Erstellt SEO-optimierte Artikel.
version: 1.2.0
author: Max Mustermann
tags: [seo, content, writing]
license: MIT
enabled: true
created: 2025-10-01
updated: 2025-11-15
priority: 10
---

Diese Meta-Felder haben keine direkte Auswirkung auf Claudes Verhalten, sondern dienen:

Der Versionierung und Wartung
Der Kategorisierung und Suche
Der Dokumentation für Teams
Der Priorisierung bei mehreren passenden Skills

Wichtig: Auch optionale Frontmatter-Felder bleiben Teil des minimal geladenen Metadatenblocks und verbrauchen nur wenige zusätzliche Tokens. Das Prinzip der Progressive Disclosure bleibt erhalten.

Best Practices für Skill-Authoring

1. Fokussiert bleiben

Halte die SKILL.md unter 500 Zeilen. Ein Skill sollte eine klar abgegrenzte Aufgabe erfüllen, nicht ein Schweizer Taschenmesser sein.

Fokussiert: pdf-text-extractor – extrahiert Text aus PDF-Dateien Zu breit: document-handler – verarbeitet PDFs, Word, Excel, Bilder, E-Mails…

Ein fokussierter Skill hat klare Trigger-Bedingungen. Bei einem “Alleskönner” weiß Claude nicht genau, wann er aktiviert werden soll – und der Nutzer weiß nicht, was er erwarten kann.

2. Präzise Trigger-Bedingungen

Die Beschreibung muss eindeutig sein, wann der Skill aktiviert werden soll:

# Unscharf
description: Hilft bei Texten

# Präzise  
description: >
  Erstellt SEO-optimierte Blogartikel in deutscher Sprache.
  Aktiviert bei Anfragen zur Content-Erstellung für Websites,
  Blog-Posts oder Landing Pages mit SEO-Fokus.

3. Konkrete Beispiele

Few-Shot-Examples sind effektiver als lange Erklärungen:

## Beispiel

**Input:**
Schreibe einen SEO-Artikel über "Cloud Computing für KMU", 
Länge ca. 1000 Wörter, Fokus-Keyword: "Cloud Computing KMU"

**Output:**
[Beispiel-Artikel mit korrekter Struktur, H1/H2/H3-Hierarchie,
Keyword-Platzierung im ersten Absatz, Meta-Description etc.]

4. Grenzen definieren

Beschreibe explizit, was der Skill nicht tut:

## Einschränkungen

- Erstellt keine rechtlich bindenden Texte
- Übersetzt nicht in andere Sprachen
- Führt keine Keyword-Recherche durch (Input muss Keywords enthalten)
- Generiert keine Bilder oder Grafiken

5. Modulare Aufteilung

Bei komplexen Workflows: Mehrere spezialisierte Skills statt eines monolithischen:

skills/
├── seo-research/          # Keyword-Recherche
├── seo-content-writer/    # Artikel-Erstellung
├── seo-meta-generator/    # Meta-Tags generieren
└── seo-audit/             # Bestehende Seiten prüfen

Skill-Speicherorte

Skills können an verschiedenen Orten abgelegt werden:

Global (für alle Projekte)

~/.claude/skills/
├── code-review/
├── seo-writer/
└── security-check/

Projektlokal

projekt/
└── .claude/
    └── skills/
        └── projekt-spezifischer-skill/

Projektlokale Skills haben Vorrang vor globalen Skills gleichen Namens.

Exkurs: Skills vs. MCP – Tokenverbrauch im Vergleich

Sowohl Skills als auch MCP (Model Context Protocol) erweitern Claudes Fähigkeiten – aber mit unterschiedlichem Tokenverbrauch.

MCP: Tools immer im Kontext

Bei MCP werden alle verfügbaren Tool-Definitionen bei jeder Anfrage in den Kontext geladen. Ein typischer MCP-Server mit 10 Tools verbraucht schnell 500-1.000 Tokens – pro Server, bei jeder Anfrage.

Kontext bei MCP-Nutzung:
├── Tool 1: github_create_issue (Schema + Beschreibung)    ~80 Tokens
├── Tool 2: github_list_repos (Schema + Beschreibung)      ~60 Tokens
├── Tool 3: github_create_pr (Schema + Beschreibung)       ~90 Tokens
└── ... 7 weitere Tools                                    ~500 Tokens
                                                    ─────────────────
                                                    Summe: ~730 Tokens

Das summiert sich bei mehreren MCP-Servern schnell auf tausende Tokens – bevor überhaupt eine Frage gestellt wurde.

Skills: Nur Metadaten bis zur Aktivierung

Skills laden initial nur Name und Beschreibung – etwa 30-50 Tokens pro Skill:

Kontext bei Skill-Nutzung (vor Aktivierung):
├── seo-content-writer: "Erstellt SEO-Artikel..."          ~40 Tokens
├── code-reviewer: "Analysiert Code auf..."                ~35 Tokens
├── data-privacy-checker: "Prüft DSGVO..."                 ~38 Tokens
└── ... 10 weitere Skills                                  ~400 Tokens
                                                    ─────────────────
                                                    Summe: ~513 Tokens

Erst wenn ein Skill aktiviert wird, werden die vollständigen Instruktionen geladen. Bei 13 Skills sind das initial ~500 Tokens – bei MCP wären es mit 13 Servern mehrere tausend.

Wann was sinnvoll ist

Aspekt	Skills	MCP
Token-Effizienz	Hoch (Progressive Disclosure)	Niedriger (alles immer geladen)
Externe Systeme	Nein	Ja (APIs, Datenbanken, Services)
Verhaltenssteuerung	Ja (Prompts, Workflows)	Nein (nur Tool-Aufrufe)
Echtzeit-Daten	Nein	Ja

Fazit: Skills eignen sich für Verhaltensanweisungen und Workflows, MCP für externe Datenquellen und Aktionen. Für maximale Token-Effizienz: Skills für Anleitungen, MCP nur für tatsächlich benötigte externe Integrationen.

Kontextgrenzen und Risiken

Trotz Progressive Disclosure bleiben Grenzen:

Token-Limits sind real

Wenn ein Skill aktiviert wird und 2.000 Tokens verbraucht, fehlen diese für andere Inhalte. Bei mehreren gleichzeitig aktiven Skills summiert sich das.

Context Pollution

Alte Konversationsinhalte können den Skill-Kontext “verschmutzen”. Lange Sessions mit vielen Skill-Wechseln können zu inkonsistentem Verhalten führen.

Lösung: Session-Splitting – für neue Aufgaben neue Sessions starten.

Halluzinationen

Selbst mit präzisen Skill-Anweisungen kann Claude falsche Informationen erzeugen. Skills reduzieren das Risiko durch klare Strukturvorgaben, eliminieren es aber nicht.

Eine vollständige SKILL.md für SEO-Content:

---
name: seo-content-writer
description: >
  Erstellt SEO-optimierte deutsche Artikel mit korrekter
  Keyword-Dichte, semantischer Struktur und Meta-Informationen.
  Aktiviert bei Anfragen zur Blog-Erstellung, Content-Writing
  oder SEO-Texterstellung.
version: 2.0.0
author: Content-Team
tags: [seo, content, marketing]
---

# SEO Content Writer

## Übersicht

Dieser Skill erstellt suchmaschinenoptimierte Artikel in deutscher 
Sprache. Er berücksichtigt aktuelle SEO-Best-Practices und 
produziert strukturierte, lesbare Inhalte.

## Voraussetzungen

Der User muss angeben:
- Thema oder Titel
- Fokus-Keyword (Hauptkeyword)
- Optional: Nebenkeywords, Zielgruppe, gewünschte Länge

## Ausführungsschritte

1. **Strukturplanung**
   - Erstelle Gliederung mit H2/H3-Hierarchie
   - Plane Keyword-Verteilung (Fokus-Keyword in H1, ersten 100 Wörtern, 
     2-3 H2s, Fazit)

2. **Einleitung**
   - Hook in den ersten 1-2 Sätzen
   - Fokus-Keyword im ersten Absatz
   - Klares Nutzenversprechen

3. **Hauptteil**
   - Logische Abschnittsfolge
   - Ein Hauptgedanke pro Absatz
   - Nebenkeywords natürlich einstreuen
   - Interne Verlinkungsmöglichkeiten markieren

4. **Abschluss**
   - Zusammenfassung der Kernpunkte
   - Call-to-Action oder weiterführende Fragen
   - Fokus-Keyword erneut erwähnen

5. **Meta-Informationen**
   - Meta-Title (50-60 Zeichen, Keyword vorne)
   - Meta-Description (150-160 Zeichen, mit CTA)
   - Slug-Vorschlag

## Stilrichtlinien

- Aktive Sprache bevorzugen
- Kurze Sätze (max. 20 Wörter im Schnitt)
- Keine Füllwörter
- Fachbegriffe erklären
- Aufzählungen und Listen nutzen

## Keyword-Dichte

- Fokus-Keyword: 1-2% (natürliche Verteilung)
- Nebenkeywords: je 0,5-1%
- Keine Keyword-Stuffing

## Output-Format

Der Artikel soll folgende Struktur haben:
- H1 mit Fokus-Keyword
- Einleitung mit Hook und Keyword
- H2-Abschnitte mit logischer Gliederung
- Fazit mit Zusammenfassung und Keyword
- Meta-Title (50-60 Zeichen)
- Meta-Description (150-160 Zeichen)
- Slug-Vorschlag

## Beispiel

**Input:**
Thema: Cloud Computing für kleine Unternehmen
Fokus-Keyword: Cloud Computing KMU
Nebenkeywords: Cloud-Lösung, Digitalisierung Mittelstand
Länge: ca. 1200 Wörter

**Output:**
[Vollständiger Artikel gemäß Format...]

## Einschränkungen

- Keine Keyword-Recherche (Keywords müssen geliefert werden)
- Keine Bildgenerierung
- Keine rechtlichen oder medizinischen Inhalte
- Nur deutsche Sprache

Zusammenhang mit Context Engineering

Skills sind ein praktisches Werkzeug für Context Engineering – die systematische Bereitstellung von strukturiertem Kontext für KI-Systeme.

Während Context Engineering das “Was” und “Warum” beschreibt (welche Informationen braucht die KI?), liefern Skills das “Wie” (modulare, on-demand ladbare Kontextbausteine).

Die Kombination aus:

CLAUDE.md (projektweite Grundkonfiguration)
Skills (spezialisierte, bedarfsgesteuerte Fähigkeiten)
MCP-Server (externe Datenquellen und Tools)

bildet das Fundament für leistungsfähige, skalierbare KI-Assistenten.

Modulare Skills statt Mega-Prompts

Das Skills-System mit SKILL.md als zentralem Manifest löst ein fundamentales Problem von KI-Agenten: Wie können viele spezialisierte Fähigkeiten verfügbar sein, ohne das Kontextfenster zu überlasten?

Die Antwort ist elegantes Progressive Disclosure:

Metadaten immer geladen (minimal)
Vollständiger Inhalt nur bei Bedarf
Ressourcen nur wenn referenziert

Für Entwickler und Power-User bedeutet das: Investition in gut strukturierte Skills zahlt sich aus. Ein präzise definierter Skill mit klaren Triggern, konkreten Beispielen und dokumentierten Grenzen arbeitet zuverlässiger als ein vager “Alleskönner”-Prompt.

Die Zukunft gehört modularen, wartbaren Skill-Bibliotheken – nicht monolithischen Mega-Prompts.