Eigene Skills für Claude Code definieren: Team-Fähigkeiten paketieren

1. Was ein Skill technisch ist

Ein Skill ist im Kern eine Sammlung paketierter Anweisungen, die Claude Code für eine bestimmte wiederkehrende Aufgabe lädt, sobald der Kontext einer Anfrage dazu passt. Anders als eine einzelne Prompt-Formulierung, die nur für eine Sitzung gilt, liegt ein Skill als Datei im Projekt oder global im Benutzerverzeichnis vor und steht damit dauerhaft und für jedes Teammitglied gleichermaßen zur Verfügung, sofern das Verzeichnis geteilt wird.

Technisch besteht ein Skill aus einer beschreibenden Datei mit Metadaten, typischerweise Name und Beschreibung, sowie dem eigentlichen Anweisungstext, der beim Aktivieren in den Kontext geladen wird. Ergänzend können weitere Dateien im selben Verzeichnis liegen, etwa Beispiel-Snippets, Checklisten oder Referenzdokumente, die der Skill bei Bedarf zusätzlich nachlädt, statt alles in einer einzigen, überladenen Datei zu bündeln.

2. Abgrenzung zu Slash-Commands

Ein Slash-Command wird explizit vom Nutzer aufgerufen, etwa durch die Eingabe eines Befehls wie /deploy, und führt eine feste, vorab definierte Aktion aus. Der Nutzer entscheidet bewusst, wann dieser Befehl ausgeführt wird, und der Ablauf ist in aller Regel deterministisch und wenig variabel zwischen verschiedenen Aufrufen.

Ein Skill dagegen wird in der Regel nicht explizit aufgerufen, sondern anhand seiner Beschreibung automatisch erkannt und geladen, wenn eine Anfrage inhaltlich dazu passt. Das macht Skills besser geeignet für Wissen und Vorgehensweisen, die situativ relevant werden, während Slash-Commands die bessere Wahl für klar abgegrenzte, wiederholt gleich ablaufende Aktionen bleiben, die ein Nutzer bewusst auslösen möchte.

3. Abgrenzung zu Subagents

Ein Subagent ist eine eigenständige Ausführungseinheit mit eigenem Kontextfenster, eigenen Werkzeugberechtigungen und oft einem eigenen, spezialisierten Systemprompt, die für eine abgegrenzte Teilaufgabe gestartet wird und ihr Ergebnis anschließend an die aufrufende Sitzung zurückgibt. Subagents eignen sich für Aufgaben, die viel eigenen Kontext verbrauchen und deshalb den Hauptkontext nicht belasten sollen, etwa eine ausführliche Codebasis-Recherche.

Ein Skill dagegen läuft innerhalb derselben Sitzung und desselben Kontextfensters wie die Hauptunterhaltung, fügt lediglich zusätzliches Wissen oder eine zusätzliche Vorgehensweise hinzu, ohne eine eigene, isolierte Ausführungsumgebung zu starten. Wo ein Subagent eine Aufgabe eigenständig löst, liefert ein Skill dem Hauptmodell das Handwerkszeug, um die Aufgabe selbst besser zu lösen.

4. Aufbau eines Skill-Verzeichnisses

Ein Skill lebt in einem eigenen Verzeichnis, das eine zentrale Datei mit einem strukturierten Kopfbereich für Metadaten und einem anschließenden Anweisungstext enthält. Der Kopfbereich definiert typischerweise einen eindeutigen Namen und eine präzise Beschreibung, wann der Skill greifen soll, weil genau diese Beschreibung darüber entscheidet, ob Claude Code den Skill in einer passenden Situation überhaupt findet und lädt.

Zusätzliche Dateien im selben Verzeichnis, etwa eine Referenz-Checkliste oder ein Beispielskript, werden nicht automatisch vollständig geladen, sondern nur bei tatsächlichem Bedarf nachgezogen. Das hält den Basis-Kontext schlank und erlaubt gleichzeitig, umfangreiches Detailwissen bereitzuhalten, ohne jede Sitzung von Anfang an damit zu belasten.

# Typische Verzeichnisstruktur eines Team-Skills
.claude/skills/code-review-checkliste/
├── SKILL.md              # Metadaten + Kernanweisungen
├── checkliste.md          # Ausführliche Prüfpunkte, nur bei Bedarf geladen
└── beispiele/
    └── security-issue.md  # Beispielhafte Fundstelle mit Begründung

5. Wann sich ein eigener Skill lohnt

Ein eigener Skill lohnt sich, sobald eine bestimmte Vorgehensweise regelmäßig im Team gebraucht wird und sich nicht in wenigen Sätzen erschöpfend beschreiben lässt, etwa eine mehrstufige Code-Review-Checkliste, eine projektspezifische Konvention für Datenbankmigrationen oder ein wiederkehrendes Debugging-Vorgehen für eine bestimmte Fehlerklasse. Für einmalige oder sehr einfache Anweisungen lohnt sich der Aufwand eines eigenen Skills dagegen selten, hier reicht ein direkter Prompt völlig aus.

Ein gutes Kriterium ist die Häufigkeit: Wird eine bestimmte Anweisung mehrmals pro Woche im Team wiederholt formuliert, ist das ein starkes Indiz dafür, dass ein Skill die Konsistenz verbessert und Zeit spart. Wird eine Anweisung dagegen nur einmalig gebraucht, bleibt ein einfacher, direkt formulierter Prompt die effizientere Wahl.

6. Praktisches Beispiel: Team-Skill für eine Code-Review-Checkliste

Ein realistisches Team-Beispiel ist ein Skill, der eine standardisierte Code-Review-Checkliste durchsetzt: Prüfung auf fehlende Tests, unsichere Datenbankabfragen, fehlende PHPDoc-Blöcke und Verstöße gegen projektspezifische Konventionen. Statt diese Checkliste bei jedem Review erneut zu erklären, lädt Claude Code den Skill automatisch, sobald eine Anfrage nach einem Code-Review erkennbar ist, und wendet die Kriterien konsistent an.

Der Vorteil gegenüber einer reinen CLAUDE.md-Regel liegt in der gezielten Aktivierung: Die Checkliste belastet den Kontext nur dann, wenn tatsächlich ein Review ansteht, nicht bei jeder beliebigen Anfrage im Projekt. Das hält alltägliche Aufgaben schlank und stellt gleichzeitig sicher, dass bei einem Review nichts Wichtiges vergessen wird.

---
name: code-review-checkliste
description: >
  Wird verwendet, wenn ein Code-Review angefordert wird oder ein
  Pull Request bewertet werden soll. Prüft auf fehlende Tests,
  unsichere Datenbankabfragen, fehlende PHPDoc-Blöcke und
  Verstöße gegen die im Projekt festgelegten Konventionen.
---

# Code-Review-Checkliste

Bei jedem angeforderten Review folgende Punkte systematisch prüfen:

1. Sind für neue öffentliche Methoden Unit-Tests vorhanden?
2. Werden Datenbankabfragen ausschließlich über Repositories
   und niemals mit rohem SQL im Controller ausgeführt?
3. Hat jede neue Klasse und Methode einen vollständigen PHPDoc-Block?
4. Werden Service Contracts statt konkreter Klassen injiziert?

7. Wie Skills aktiviert und getriggert werden

Die Aktivierung eines Skills basiert auf einem Abgleich zwischen der Beschreibung im Kopfbereich und dem Inhalt der aktuellen Anfrage. Eine zu allgemein formulierte Beschreibung führt dazu, dass der Skill entweder viel zu häufig geladen wird und unnötig Kontext verbraucht, oder umgekehrt in Situationen nicht greift, in denen er eigentlich gebraucht würde, weil die Formulierung zu weit von der tatsächlichen Nutzeranfrage entfernt ist.

Eine präzise, konkrete Beschreibung mit typischen Auslösewörtern und -situationen verbessert die Trefferquote deutlich. Es lohnt sich, die Beschreibung nach den ersten praktischen Erfahrungen im Team anzupassen, wenn sich zeigt, dass der Skill in bestimmten erwarteten Situationen nicht automatisch geladen wird.

8. Team-Verteilung und Versionierung von Skills

Ein Skill entfaltet seinen vollen Wert erst, wenn er im Projekt-Repository versioniert und damit für das gesamte Team automatisch verfügbar ist, statt nur lokal bei einer einzelnen Person zu existieren. Über die normale Versionsverwaltung lassen sich Änderungen an einem Skill nachvollziehen, im Code-Review diskutieren und bei Bedarf rückgängig machen, genau wie bei jeder anderen projektrelevanten Konfigurationsdatei.

Für teamübergreifende Fähigkeiten, die über ein einzelnes Projekt hinaus gelten, etwa allgemeine Coding-Standards, kann ein Skill zusätzlich global im Benutzerverzeichnis abgelegt werden. Sinnvoll ist eine klare Trennung: projektspezifische Skills im Repository, allgemeine, projektübergreifende Skills global, damit keine Vermischung entsteht und jeder Skill an der richtigen Stelle gepflegt wird.

9. Best Practices und typische Fallstricke

Der häufigste Fehler beim Einstieg ist eine zu umfangreiche, monolithische Skill-Datei, die alles auf einmal abdecken soll und dadurch unübersichtlich wird. Besser ist es, mehrere kleine, klar abgegrenzte Skills mit präzisen Beschreibungen anzulegen, statt einen einzelnen Skill für sämtliche Teamkonventionen zu überladen. Zusatzmaterial gehört in separate, nur bei Bedarf geladene Dateien statt in die Hauptdatei.

Ein weiterer typischer Fallstrick ist mangelnde Pflege: Ein Skill, der einmal erstellt und danach nie wieder aktualisiert wird, veraltet mit der Zeit genauso wie jede andere Dokumentation. Skills sollten deshalb denselben Review- und Pflegezyklus durchlaufen wie der übrige Projektcode, idealerweise mit einer klaren Verantwortlichkeit im Team, wer Änderungen an welchem Skill vornimmt.

10. Zusammenfassung

11. FAQ: Eigene Skills definieren: Das Wichtigste auf einen Blick