Claude Code Skills: Wie Sie wiederkehrende Abläufe als Skill festhalten

Was Skills in Claude Code sind

Ein Skill (Fähigkeit oder Ablauf) ist ein Ordner mit einer Datei SKILL.md, in der eine Anweisung für einen bestimmten Aufgabentyp steht: wie ein Projekt ausgeliefert wird, wie ein Review abläuft, wie ein Release entsteht. Der Agent kennt den Skill vom Beginn der Sitzung an, liest ihn aber erst vollständig, wenn die Aufgabe das tatsächlich verlangt.

Skills lösen ein Problem, das jeder kennt, der lange eine CLAUDE.md pflegt: Die Datei wächst. Ein Deployment-Ablauf mit 80 Zeilen wird einmal pro Woche gebraucht, belegt aber in jeder Sitzung Platz im Kontext — auch dann, wenn Sie nur einen Tippfehler im README korrigieren. Ein Skill lagert solche Abläufe aus dem ständigen Kontext aus und bindet sie bei Bedarf ein.

Aus was ein Skill besteht

Ein minimaler Skill ist ein Ordner und eine Datei. Projektbezogene Skills liegen im Repository, persönliche im Home-Verzeichnis des Benutzers:

.claude/skills/deploy/SKILL.md      # Skill des Projekts, für das Team über git geteilt
~/.claude/skills/review/SKILL.md    # persönlicher Skill, in allen Projekten verfügbar

Neben der SKILL.md können Sie Hilfsdateien ablegen: Vorlagen, Skripte, Nachschlagewerke. Der Agent öffnet sie nur, wenn der Haupttext auf sie verweist und sie gebraucht werden:

.claude/skills/deploy/
├── SKILL.md           # Hauptanleitung
├── checklist.md       # ausführliche Checkliste, wird über den Verweis gelesen
└── rollback.sh        # Skript für den Rollback

Frontmatter: name und description

Die Datei beginnt mit einem YAML-Block zwischen den Zeilen ---. Zwei Felder sind wichtiger als alle anderen: name — der kurze Name des Skills, und description — die Beschreibung, was der Skill tut und wann er anzuwenden ist.

---
name: deploy
description: Deployment der Website auf den Hosting-Server per FTP. Verwenden, wenn Änderungen auf den Server müssen, Abweichungen zum Server geprüft werden sollen oder ein Deployment zurückgerollt werden muss.
---

# Deployment

1. Zuerst einen Probelauf: `./deploy.sh -n`.
2. Die Dateiliste prüfen: Sie darf keine Geheimnisse und Testskripte enthalten.
3. Hochladen: `./deploy.sh`.
4. Die geänderten Seiten öffnen und sicherstellen, dass sie mit 200 antworten.

Rollback — siehe rollback.sh in diesem Ordner.

Unterhalb des Frontmatters steht gewöhnliches Markdown: Schritte, Befehle, Einschränkungen, Verweise auf Nachbardateien. Schreiben Sie es so, wie Sie eine Anleitung für einen neuen Kollegen schreiben würden, der diese Aufgabe zum ersten Mal erledigt.

Wann der Agent einen Skill lädt

Zu Beginn der Sitzung gelangen nur Name und Beschreibung jedes verfügbaren Skills in den Kontext. Das sind wenige Zeilen pro Skill, deshalb können Sie dutzende davon halten. Stimmt die Anfrage des Benutzers oder der aktuelle Schritt der Arbeit mit der Beschreibung überein, ruft der Agent den Skill auf — und erst dann wird der vollständige Text der SKILL.md geladen.

Daraus folgt die wichtigste praktische Regel: Ein Skill wird über seine Beschreibung ausgelöst. Der Agent sieht den Text des Skills nicht, bevor er entschieden hat, ihn zu öffnen. Steht in der description »Hilfsskill«, versteht der Agent nicht, wann er gebraucht wird. Steht dort »Deployment auf den Hosting-Server; verwenden, wenn Änderungen auf den Server müssen oder ein Rollback nötig ist«, dann versteht er es.

Neben der automatischen Auswahl können Sie einen Skill auch direkt aufrufen — per Name mit einem Schrägstrich, etwa /deploy. Das ist praktisch, wenn Sie genau wissen, welcher Ablauf nötig ist, und nicht darauf vertrauen wollen, dass der Agent die Anfrage selbst zuordnet.

Wie Sie die description so schreiben, dass der Skill ausgelöst wird

• Was er tut — in einem Satz, mit einem Verb: »Deployment der Website«, »Review der Änderungen vor dem Commit«.
• Wann er verwendet wird — nennen Sie die Formulierungen, mit denen der Benutzer diese Aufgabe tatsächlich beschreibt: »lade auf den Server hoch«, »veröffentliche«, »rolle zurück«.
• Wann er nicht verwendet wird, wenn der Skill leicht mit einem benachbarten verwechselt wird: »nicht für das Deployment des Bots, nur für die Website«.
• Keine allgemeinen Floskeln wie »nützlicher Skill« oder »hilft bei der Arbeit« — sie tragen kein Signal.

Schrittweises Laden

Skills folgen dem Prinzip des schrittweisen Offenlegens (progressive disclosure): Die Informationen werden in Schichten bereitgestellt, und jede folgende Schicht wird erst geladen, wenn sie gebraucht wird.

Das ist dieselbe Idee wie ein Wegweiser statt einer Papierflut in der Anweisungsdatei: eine kurze Übersicht ist immer griffbereit, die Details liegen hinter einem Verweis. Der Unterschied ist, dass der Skill dieses Laden zum festen Mechanismus macht und nicht darauf setzt, dass der Agent das richtige Dokument selbst öffnet. Ein weiterer Vorteil: Ein Skript aus der dritten Schicht kann der Agent einfach ausführen, ohne seinen gesamten Code in den Kontext zu laden.

Skills, CLAUDE.md und Slash-Befehle: Der Unterschied

Alle drei Mechanismen geben dem Agenten Anweisungen, aber zu unterschiedlichen Zeitpunkten und mit unterschiedlichen Kosten für den Kontext.

Die Auswahlregel ist einfach. Wird eine Anweisung in fast jeder Aufgabe gebraucht, gehört sie in die CLAUDE.md. Wird sie in Aufgaben eines bestimmten Typs gebraucht, ist es ein Skill. Tippen Sie jedes Mal denselben langen Auftrag ein, ist das ein Kandidat für einen Befehl oder einen manuell aufrufbaren Skill.

Harte Verbote gehören nicht in einen Skill. Der Skill wird vielleicht gar nicht geladen, die Regel »committe niemals Geheimnisse« muss aber immer gelten. Solche unveränderlichen Vorgaben bleiben in der CLAUDE.md und werden nach Möglichkeit durch Mechanik abgesichert: Hooks, Zugriffsrechte, Prüfungen in der CI.

Wie Sie einen Skill für Claude Code schreiben: Schritt für Schritt

1. Finden Sie den wiederkehrenden Ablauf. Ein gutes Zeichen: Sie haben dem Agenten dreimal dasselbe erklärt, oder die CLAUDE.md enthält einen Abschnitt, der nur in einer von zehn Aufgaben gebraucht wird.
2. Legen Sie den Ordner .claude/skills/<name>/ und darin eine Datei SKILL.md an.
3. Schreiben Sie das Frontmatter mit name und description, in der ausdrücklich steht, wann der Skill anzuwenden ist.
4. Beschreiben Sie die Schritte mit konkreten Befehlen und Kriterien der Fertigstellung: was zu prüfen ist und welches Ergebnis als Erfolg gilt.
5. Lagern Sie Langes aus in Nachbardateien und verweisen Sie aus dem Haupttext darauf.
6. Entfernen Sie die Dublette aus der CLAUDE.md und lassen Sie nur eine Verweiszeile stehen: »Deployment — Skill deploy«.
7. Prüfen Sie es: Bitten Sie in einer neuen Sitzung um die Aufgabe mit eigenen Worten, ohne den Namen des Skills zu nennen, und sehen Sie nach, ob der Agent ihn aufgreift. Wenn nicht, schreiben Sie die Beschreibung um.

Beispiele für Skills

Skill für das Deployment

Ein klassischer Kandidat: Der Ablauf ist selten, lang und gefährlich, und ein Fehler kostet viel. Im Skill stehen die Reihenfolge der Schritte (zuerst Probelauf, dann Hochladen), was nicht hochgeladen werden darf, wie das Ergebnis zu prüfen ist und wie man zurückrollt. Der Agent muss das bei jeder Codeänderung nicht im Kopf behalten — nur dann, wenn es um den Server geht.

Skill für das Review

---
name: review
description: Review der aktuellen Änderungen vor dem Commit. Verwenden, wenn der Diff geprüft werden soll, Fehler in den Änderungen gesucht werden oder Änderungen für einen Commit vorbereitet werden.
---

# Review der Änderungen

1. Diff holen: `git diff` und `git diff --staged`.
2. Für jede geänderte Datei prüfen:
   - Benutzereingaben werden bei der Ausgabe maskiert;
   - SQL-Abfragen sind parametrisiert;
   - keine Debug-Ausgaben und keine temporären Dateien.
3. Tests und Linter des Projekts starten (Befehle stehen in der CLAUDE.md).
4. Bericht: Liste der Probleme mit Datei und Zeile, von den schweren zu den kleinen. Gibt es keine Probleme, das so schreiben, ohne erfundene Anmerkungen.

Ein solcher Skill macht aus »schau, ob alles in Ordnung ist« eine wiederholbare Prüfung mit jedes Mal derselben Punkteliste.

Skill für das Beenden der Sitzung

Ein weiterer nützlicher Typ ist das Ritual am Ende der Arbeit: die lokale Umgebung anhalten, temporäre Dateien löschen, im Fortschrittsjournal festhalten, was erledigt ist und was noch offen ist, und einen Commit mit ausführlicher Beschreibung machen. Das behebt direkt den Kontextverlust zwischen Sitzungen: Die nächste Sitzung beginnt mit dem aktuellen Stand des Repositorys und nicht mit Vermutungen.

Typische Fehler

• Unscharfe Beschreibung. Der Skill existiert, aber der Agent ruft ihn nicht auf. Abhilfe: die description mit konkreten Auslösern neu formulieren.
• Skill als Textwand. Der gesamte alte Abschnitt mit 400 Zeilen wurde in die SKILL.md übertragen. Das Problem des aufgeblähten Kontexts ist zurück, nur später. Halten Sie den Haupttext kurz und die Details in Nachbardateien.
• Doppelung mit der CLAUDE.md. Derselbe Ablauf steht an zwei Stellen und driftet mit der Zeit auseinander. Es muss eine einzige Quelle der Wahrheit geben.
• Überlappende Skills. Zwei Skills mit ähnlichen Beschreibungen — der Agent wählt zufällig. Trennen Sie sie durch klare Angaben »verwenden / nicht verwenden«.
• Veraltete Befehle. Ein Skript wurde umbenannt, der Skill verweist aber noch auf den alten Namen. Der Skill ist Teil des Projektcodes: Aktualisieren Sie ihn im selben Commit wie den Ablauf.

Wann Sie einen Abschnitt in einen Skill auslagern sollten

Gehen Sie die CLAUDE.md regelmäßig durch und fragen Sie bei jedem Abschnitt: In welchem Anteil der gewöhnlichen Aufgaben wird er tatsächlich gebraucht? Wird er fast immer gebraucht, gehört er dorthin. Wird er in einer von zehn Aufgaben gebraucht, ist er ein Kandidat für einen Skill.

Ein zweites Signal ist die Länge. Ein Abschnitt, der nicht auf einen Bildschirm passt, beschreibt fast sicher einen Ablauf und keine Regel. Abläufe liest man besser vollständig im Moment der Ausführung, als sie während der ganzen Sitzung im Hintergrund zu halten.

Ein drittes Signal sind wiederholte Erklärungen. Wenn Sie dem Agenten immer wieder dieselben Ergänzungen zu derselben Aufgabe geben, schreiben Sie sie einmal in einen Skill. Schauen Sie nach einer Woche nach, ob die manuellen Korrekturen zurückgegangen sind: Das ist der Nachweis, dass der Skill funktioniert.

Fazit

Skills in Claude Code sind eine Möglichkeit, Abläufe neben dem Projekt aufzubewahren, ohne in jeder Sitzung Kontext dafür zu bezahlen. Die Beschreibung eines Skills ist immer sichtbar, der Text wird bei Bedarf geladen, Hilfsdateien noch später. In der CLAUDE.md bleiben die Übersicht über das Projekt und die harten Regeln, in Skills wandern Deployment, Review, Releases und andere Aufgaben eines bestimmten Typs. Aufbau der Dateien mit Anweisungen und schrittweises Laden des Kontexts behandeln wir im Kurs zum Harness Engineering praktisch.