Erstellung von Skills für Claude Code: Von der Architektur bis zum Testen

1. Was ist ein Skill und warum er ein vollwertiges Software-Artefakt ist

Ein Skill in Claude Code ist ein standardisierter, modularer Wissenspaket, der eine Workflow-Beschreibung, eine Reihe von Domänenregeln, Verfahren oder ausführbare Skripte enthält, die ein KI-Agent automatisch lädt, um eine bestimmte Klasse von Aufgaben zu lösen. Anstatt dass Ingenieure bei jeder neuen Sitzung lange Anweisungen manuell kopieren, erkennt der Agent die Absicht des Nutzers selbstständig und aktiviert den entsprechenden Skill.

Der wesentliche Unterschied zwischen einem Skill und traditionellem Programmcode besteht darin, dass die Sprachmodellierung selbst über die Aktivierung entscheidet, basierend auf einer semantischen Abgleichung der Skill-Beschreibung mit der Nutzeranfrage. Diese Entscheidung ist probabilistisch: Es gibt keinen Compiler und keine strenge Typisierung, daher bestimmt die Präzision der Metadaten-Formulierung direkt, ob der Skill im richtigen Moment aktiviert wird.

Warum ein Skill ein ingenieurtechnisches Artefakt und kein gewöhnlicher Text ist

1. Versionierung und Modularität: Ein Skill besteht aus Standard-Repository-Dateien, wird in Git gespeichert und entwickelt sich nach denselben Gesetzen wie Anwendungscode.
2. Trennung von Schnittstelle und Implementierung: Das Feld description im Frontmatter fungiert als öffentliche Schnittstelle des Skills, während der Inhalt von SKILL.md und eingebettete Skripte die interne Implementierung darstellen.
3. Kompositionsfähigkeit: Ein Skill kann externe Tools über MCP aufrufen, Konsolen-Utilities starten und Teilaufgaben an andere Skills oder Subagents delegieren.
4. Anfälligkeit für Regressionen: Eine unsachgemäße Änderung der Beschreibung kann zu einem „silent failure“ führen (der Skill hört auf, sich zu aktivieren) oder zu Halluzinationen bei der Ausführung der Schritte.

2. Datei- und Verzeichnisstruktur: SKILL.md, Skripte und Referenzressourcen

Ein Skill ist eine strukturierte Ordner im Dateisystem, deren obligatorischer Kern die Datei SKILL.md ist. Je nach Komplexität der Aufgabe kann der Skill durch Hilfescripts, Handbücher und Vorlagen ergänzt werden.

Architektur eines Skills: Schnittstelle, Implementierung, gebündelte Ressourcen und externe Tools ЗбільшитиArchitektur eines Skills: Schnittstelle, Implementierung, gebündelte Ressourcen und externe Tools

Speicherstufen für Skills in Claude Code

• Globale Skills (~/.claude/skills/): Für den Entwickler in allen Projekten auf dem aktuellen Rechner verfügbar. Ideal für persönliche Utilities, individuelle Commit-Vorlagen oder analytische Skripte.
• Projekt-Skills (.claude/skills/): Werden direkt im Projekt-Repository gespeichert und in Git committet. Verfügbar für alle Teammitglieder, was einheitliche Architektur- und Teststandards gewährleistet.

Empfohlene Struktur für einen komplexen Skill

Ein minimaler Skill kann aus nur einer einzigen SKILL.md-Datei bestehen. Größere Systeme bündeln eigene Automatisierungsskripte und Dokumentation im Skill-Verzeichnis, um die Logik kompakt und autark zu halten.

3. Regeln für das Frontmatter: name und description

Die Datei SKILL.md beginnt zwingend mit einem Metadatenblock im YAML-Frontmatter-Format. Dies ist der einzige Teil des Skills, den Claude beim Initialisieren der Sitzung liest, um ein Verzeichnis der verfügbaren Aktionen aufzubauen.

Formale Einschränkungen für den Namen (name)

• Länge maximal 64 Zeichen.
• Erlaubt sind nur Kleinbuchstaben, Ziffern und Bindestriche ([a-z0-9-]).
• Die Verwendung von XML/HTML-Tags ist verboten.
• Reservierte Firmennamen (claude, anthropic) dürfen nicht verwendet werden.

Formale Einschränkungen für die Beschreibung (description)

• Pflichtfeld, darf nicht leer sein.
• Länge maximal 1024 Zeichen.
• Die Verwendung von XML-Tags ist verboten.
• Muss sowohl die Funktionalität des Skills als auch die kontextuellen Trigger für seine Aktivierung klar beschreiben.

4. Progressive Disclosure und Kontextfenster

Skills werden nicht vollständig in das Kontextfenster des Modells geladen, wenn die Sitzung startet. Claude Code nutzt das Prinzip des Progressive Disclosure, das in drei klare Stufen unterteilt ist.

Lineare Pipeline der Anfrageverarbeitung durch das Modell und das Kontextfenster ЗбільшитиLineare Pipeline der Anfrageverarbeitung durch das Modell und das Kontextfenster

Drei Ladestufen

1. Stufe 1 — Metadaten (Metadata): Namen und Beschreibungen aller verfügbaren Skills werden zu Beginn der Sitzung in den Systemkontext geladen. Der Aufwand beträgt etwa 100 Tokens pro Skill. Dies ermöglicht es, Dutzende von Skills in ein Projekt einzubinden, ohne das Kontextlimit auszuschöpfen.
2. Stufe 2 — Dateirumpf (Body): Wenn das Modell entscheidet, dass die Nutzeranfrage der Skill-Beschreibung entspricht, liest es den Inhalt von SKILL.md. Empfohlene Größe des Rumpfs – bis zu 500 Zeilen, um die Arbeitsgeschichte des Dialogs nicht zu verdrängen.
3. Stufe 3 — Eingebettete Dateien und Skripte (Resources): Referenzdateien (references/) werden nur gelesen, wenn die Anleitung direkt darauf verweist. Skripte werden meist über den bash-Interpreter ausgeführt: Ihr Code gelangt gar nicht ins Kontextfenster, zurückgegeben wird nur das finale Ausführungsergebnis.

5. Formulierung der description: Erstellung zuverlässiger Aktivierungs-Trigger

Da description der Haupttrigger für probabilistische Auslösung ist, sollte seiner Formulierung besondere Aufmerksamkeit gewidmet werden.

Regeln für eine effektive Beschreibung

• Nur dritte Person: Schreiben Sie die Beschreibung in der dritten Person (Generates, Performs, Audits). Das Modell nimmt die Beschreibung als Systemspezifikation des Tools wahr; Pronomen der ersten oder zweiten Person (I will, You can) verschlechtern die Qualität des Abgleichs.
• Formel „Was + Wann“: Die Beschreibung muss klar zwei Fragen beantworten: Was genau tut der Skill und in welchen Situationen muss er angewendet werden.
• Reale Schlüsselwörter: Nehmen Sie spezifische technische Begriffe, Dateinamen oder Befehle auf, die der Nutzer garantiert in seiner Anfrage erwähnen wird.

6. Anatomie eines vorbildlichen Skills: Schritt-für-Schritt-Analyse des release-notes-Pipelines

Betrachten wir die praktische Architektur eines Skills zur Automatisierung der Release-Dokumentation release-notes.

Schrittweiser Ausführungs-Pipeline des Skills release-notes mit Argumenten und Ressourcen ЗбільшитиSchrittweiser Ausführungs-Pipeline des Skills release-notes mit Argumenten und Ressourcen

Komponenten des Workflows

• Eingabeparameter: Benutzerargumente (Tag-Bereich v1.2.0..v1.3.0), Stilhandbuch changelog-style.md, Hilfsskript gather-prs.py.
• Schrittfolge in SKILL.md:
  1. Bestimmen des Release-Tag-Bereichs in git.
  2. Ausführen des Skripts python scripts/gather-prs.py zum Abrufen einer strukturierten Liste von Commits.
  3. Gruppieren der Änderungen nach Kategorien (Features, Fixes, Performance, Breaking Changes).
  4. Erstellen eines Entwurfs gemäß dem Stil in changelog-style.md.
  5. Schreiben des aktualisierten Blocks in CHANGELOG.md und Ausgabe einer kurzen Zusammenfassung.
• Ausgabeartefakte: Aktualisierte Datei CHANGELOG.md und eine prägnante Nachricht für das Team.

Architekturregeln für den Dateirumpf

1. Wiederholen Sie keine allgemein bekannten Dinge: Gehen Sie davon aus, dass Claude bereits ein qualifizierter Ingenieur ist. Beschreiben Sie nur die Spezifika Ihres Projekts und strenge Unternehmensanforderungen.
2. Referenztiefe – nur eine Ebene: Referenzdateien sollten nicht kettenweise auf andere Dateien verweisen. Alle Materialien müssen direkt an SKILL.md gebunden sein.
3. Plattformübergreifende Pfade: Verwenden Sie immer gerade Schrägstriche (/) in allen Pfaden zu Dateien und Konfigurationen.

7. Landschaft der Anpassungen: Skills, CLAUDE.md, Slash-Kommandos, MCP, Hooks und Plugins

In Claude Code gibt es mehrere Instrumente zur Steuerung des Agentenverhaltens. Die falsche Wahl des Mechanismus ist die häufigste Ursache für Systemunzuverlässigkeit.

Matrix der Anpassungsmechanismen in Claude Code: Wer initiiert den Start vs. Einflussstärke ЗбільшитиMatrix der Anpassungsmechanismen in Claude Code: Wer initiiert den Start vs. Einflussstärke

8. Skills vs. Hooks: Balance zwischen Empfehlungen und Runtime-Garantien

Anfänger versuchen oft, Skills für Sicherheitsaufgaben oder erzwingende Code-Formatierung zu nutzen. Dies ist ein konzeptueller Fehler: Ein Skill garantiert keine Ausführung, er lehrt das Modell nur den richtigen Ansatz.

Lebenszyklus der Claude-Code-Sitzungsausführung und Integrationspunkte für Hooks und Skills ЗбільшитиLebenszyklus der Claude-Code-Sitzungsausführung und Integrationspunkte für Hooks und Skills

Punkte im Lebenszyklus der Ausführung

• SessionStart (Hook): Tritt beim Öffnen der Sitzung auf. Garantiert die Initialisierung von Umgebungsvariablen oder eine vorherige Prüfung des git-Branches.
• Modell-Reasoning (Mögliches Lesen des Skills): Das Modell analysiert die Aufgabe und trifft Entscheidungen über das Laden des SKILL.md-Rumpfs.
• PreToolUse (Hook, blockierend): Wird unmittelbar vor dem Aufruf eines Tools ausgeführt. Kann einen bash-Befehl prüfen und dessen Ausführung blockieren (Rückgabecode 2), wenn er Sicherheitsregeln verletzt.
• PostToolUse (Hook): Analysiert das Ergebnis der Befehlsausführung oder Dateiänderung (startet z.B. automatisch Prettier nach dem Speichern einer Datei).
• Stop (Hook): Tritt nach Abschluss der Antwortgenerierung durch das Modell auf.

9. Entwicklungsprozess durch Bewertung (Evaluation-Driven Development)

Die Erstellung eines zuverlässigen Skills erfordert iteratives Testen in realen Szenarien, noch bevor der endgültige Anleitungstext geschrieben wird.

Vier Phasen der Skill-Erstellung

1. Fixierung des Baseline-Niveaus (Baseline): Führen Sie Claude Code in typischen Arbeitsaufgaben ohne Skill aus. Dokumentieren Sie, wo genau das Modell Fehler macht, Schritte überspringt oder zusätzliche Klärungen benötigt.
2. Erstellung von Testfällen (Eval Suite): Verwandeln Sie dokumentierte Fehler in eine Liste von Kontrollaufgaben mit klar definierten erwarteten Ergebnissen.
3. Schreiben des minimalen Textes (MVP): Formulieren Sie einen minimalen Satz von Anweisungen in SKILL.md, der ausreicht, um die Tests erfolgreich zu bestehen.
4. Iterative Feinabstimmung: Fügen Sie Regeln und Ausnahmen nur als Reaktion auf konkrete Testfall-Fehler hinzu, vermeiden Sie dabei die Aufblähung des Kontexts.

Workflow mit zwei Modellinstanzen

Beim Design eines Skills wird empfohlen, zwei parallele Terminals zu verwenden:

• Editor-Instanz: Eine Sitzung, in der Sie gemeinsam mit Claude den Text des neuen Skills formulieren, ergänzen und strukturieren.
• Tester-Instanz: Eine saubere Sitzung, in der Sie Testanfragen ausführen und überprüfen: Ob der Skill automatisch erkannt wird, ob die Schritte korrekt interpretiert werden und ob die resultierenden Dateien valide sind.

10. Übliche Design-Patterns und Anti-Patterns bei der Erstellung von Skills

Die praktische Erfahrung der Community hat eine Reihe bewährter Vorlagen und typischer Fehler hervorgehoben, die vermieden werden sollten.

Effektive Engineering-Patterns

• Nummerierte deterministische Sequenzen: Strukturieren Sie Schritte für komplexe mehrstufige Aktionen immer als 1. ..., 2. ..., 3. ....
• Eingebaute Validierungs-Checklisten: Fügen Sie für kritische Operationen eine Checkliste hinzu, die das Modell in die Antwort kopieren und abhaken muss, je nach Fortschritt.
• Selbstprüfungs-Zyklen (Verify & Fix): Definieren Sie die Regel: „Linter starten -> Fehler beheben -> erneut prüfen bis zur sauberen Ausgabe“.
• Planung vor destruktiven Aktionen: Verlangen Sie für Batch-Lösch- oder Überschreiboperationen zunächst die Erstellung eines Änderungsplans in einer Markdown-Tabelle und bitten Sie um Bestätigung.

Häufige Anti-Patterns

• Paradox der Wahl: Beschreibung einer übermäßigen Anzahl alternativer Bibliotheken oder Ansätze ohne Angabe der Standardoption.
• Undeklarierte Systemabhängigkeiten: Verwendung fremder CLI-Utilities oder npm-Pakete ohne vorherige Anleitung zu ihrer Installation oder Überprüfung der Verfügbarkeit.
• Backslashes in Pfaden: Verwendung von Backslashes im Windows-Stil (src\utils\), was zu Fehlern auf Linux und macOS führt.
• Unerklärte magische Zahlen: Verwendung von Konstanten oder Timeouts ohne Kommentar zu ihrer Herkunft.

11. Sicherheit und Audit von Fremdskills vor der Installation

Jeder Fremdskill ist ausführbarer Code in Ihrer Arbeitsumgebung. Da Claude Code Zugriff auf das Dateisystem, das Terminal und das Netzwerk hat, birgt ein ungeprüfter Skill ernsthafte Sicherheitsrisiken.

Checkliste für das Audit eines Fremdskills vor der Nutzung

• Analyse des SKILL.md-Rumpfs: Prüfen Sie den Text auf versteckte Anweisungen mit Prompt Injection, Versuche, .env-Dateien zu stehlen, oder Schutzmechanismen zu deaktivieren.
• Audit eingebetteter Skripte: Untersuchen Sie sorgfältig alle Dateien im Verzeichnis scripts/. Stellen Sie sicher, dass die Skripte keine verdächtigen Netzwerkanfragen an fremde Server durchführen.
• Prüfung externer URLs: Achten Sie auf jegliche Links zum Herunterladen externer Binärdateien oder dynamischer Konfigurationen.
• Isoliertes Testen: Den ersten Start eines Fremdskills führen Sie immer in einem Test-Repository oder einer Sandbox ohne Zugriff auf Produktions-Secrets durch.