Die Agent-Skills-Spezifikation begrenzt Skill-Namen auf 64 Zeichen. Für benutzerdefinierte Skills in Claude Code sind drei Punkte entscheidend: eine verständliche SKILL.md, ein unterstütztes Verzeichnis und ein Test, der Erkennung und Verhalten prüft. Kontrollieren Sie vor der Einrichtung die aktuelle offizielle Dokumentation zu Skills, denn Pfade, optionale Metadaten und Aufrufregeln können sich ändern.
Diese Anleitung richtet sich an Entwickler, die wiederkehrende Aufgaben in Claude Code als nachvollziehbaren Ablauf festhalten möchten.
Sie hilft Teams bei der Entscheidung, ob ein Skill für ein einzelnes Projekt oder persönlich verfügbar sein soll.
Auch für den Aufbau eines KI-Agenten-Workflows ist sie geeignet, wenn Aufruf und Ergebnis überprüfbar sein müssen.
Erfolgskriterien vor dem ersten Dateischritt
>Ein Skill ist nicht schon deshalb einsatzbereit, weil eine Datei mit dem Namen SKILL.md existiert. Für eine belastbare Prüfung müssen Dateiname, Speicherort und Inhalt zusammenpassen. Anschließend muss Claude Code den Skill für eine geeignete Aufgabe erkennen oder auf einen passenden expliziten Aufruf hin verwenden. Die offiziellen Regeln für Skills in Claude Code beschreiben unterstützte Verzeichnisse und Aufrufmöglichkeiten. Maßgeblich ist die dort veröffentlichte Fassung, nicht eine ältere Anleitung oder eine kopierte Konfiguration.
Als abgeschlossen gilt die Einrichtung erst, wenn alle folgenden Punkte überprüft sind:
- Datei:
SKILL.mdliegt im Skill-Verzeichnis und enthält eine verständliche Aufgabenbeschreibung. - Geltungsbereich: Der Skill befindet sich im Projektverzeichnis oder im persönlichen Verzeichnis, das für den gewünschten Einsatz vorgesehen ist.
- Verhalten: Ein Test zeigt, dass Claude Code die Anweisungen bei einem expliziten Aufruf oder einer passenden Aufgabe berücksichtigt.
Ein sichtbarer Skill-Aufruf beweist noch nicht, dass die enthaltenen Arbeitsschritte korrekt ausgeführt werden. Umgekehrt kann eine automatische Auswahl ausbleiben, wenn die Aufgabenbeschreibung nicht zur tatsächlichen Anfrage passt. Trennen Sie beim Testen deshalb die Frage „Wurde der Skill erkannt?“ von der Frage „Hat das Ergebnis die erwarteten Vorgaben eingehalten?“. Diese Unterscheidung verkürzt die Fehlersuche: Ein Problem mit der Erkennung verlangt eine andere Korrektur als eine unvollständige Antwort nach erfolgreichem Aufruf.
Projektablage und persönliche Ablage
>Claude Code unterscheidet zwischen Skills, die zu einem Projekt gehören, und solchen, die ein Benutzer projektübergreifend einsetzen kann. Die in der Dokumentation beschriebenen Verzeichnisse sind .claude/skills/ im Projekt und ~/.claude/skills/ im Benutzerverzeichnis. Prüfen Sie die jeweils aktuelle Dokumentation, falls Ihre Installation, Arbeitsumgebung oder ein Plugin eine abweichende Konfiguration nahelegt.
| Ablage | Geeignet für | Vorteil | Zu beachten |
|---|---|---|---|
.claude/skills/<skill-name>/SKILL.md im Projekt |
Wiederkehrende Abläufe, die zu einem bestimmten Repository gehören | Die Anleitung lässt sich zusammen mit dem Projekt überprüfen und versionieren | Prüfen, ob Claude Code tatsächlich im erwarteten Projektkontext arbeitet |
~/.claude/skills/<skill-name>/SKILL.md im Benutzerverzeichnis |
Persönliche Abläufe, die in mehreren Projekten gebraucht werden | Der Skill ist nicht an ein einzelnes Repository gebunden | Die Anleitung darf keine unbeabsichtigten Annahmen über ein bestimmtes Projekt enthalten |
| Ein unterstützter Plugin-Pfad | Skills, die als Teil einer Plugin-Struktur bereitgestellt werden | Die Bereitstellung kann mit einer Plugin-Konfiguration verbunden sein | Aufbau und Einbindung müssen nach den offiziellen Regeln für Plugins geprüft werden |
Die Verzeichnisnamen sind keine bloße Konvention. Ein Skill sollte in einem eigenen Unterverzeichnis liegen, in dem sich die Datei SKILL.md befindet. Eine typische Projektstruktur sieht so aus:
projekt/
└── .claude/
└── skills/
└── change-review/
└── SKILL.md
Wählen Sie die Projektablage, wenn der Ablauf an Quellcode, Testkonventionen oder Dateipfade dieses Repositorys gebunden ist. Verwenden Sie die persönliche Ablage, wenn dieselbe Anleitung unabhängig vom Repository gelten soll. Für eine gemeinsame Teamlösung ist die Projektablage häufig einfacher zu überprüfen, weil Änderungen am Skill zusammen mit den übrigen Projektänderungen sichtbar werden. Persönliche Skills sind dagegen nicht automatisch ein geeigneter Teamstandard: Sie können lokal funktionieren, ohne dass Kollegen dieselbe Anleitung besitzen.
Wie sollte die Verzeichniskonfiguration für Claude-Code-Skills aussehen?
Beginnen Sie mit einem unterstützten Bereich und einem eigenen Unterverzeichnis mit einem kurzen, eindeutigen Namen. Legen Sie SKILL.md dort ab und prüfen Sie anschließend den tatsächlichen Pfad. Kontrollieren Sie außerdem, ob das Terminal im erwarteten Projekt startet und ob der verwendete Benutzerzugang auf das Verzeichnis zugreifen kann. Bei Plugins gelten zusätzliche Regeln; übertragen Sie deren Struktur nicht ungeprüft auf ein einfaches Projekt-Skill.
Aufbau der Datei SKILL.md
>Ein gutes SKILL.md beantwortet drei Fragen, bevor es den Ablauf beschreibt: Wofür ist der Skill gedacht? Unter welchen Bedingungen passt er? Was soll Claude Code konkret tun? Die offizielle Dokumentation zum Format und zur Verwendung von Skills erklärt Frontmatter und Inhalt. Ergänzend beschreibt die Agent-Skills-Spezifikation Formatregeln. Für eine robuste erste Fassung sollten Sie nur Metadaten verwenden, deren Schreibweise und Bedeutung Sie in den aktuellen Regeln nachvollzogen haben.
Ein kurzes Beispiel für einen Code-Review-Ablauf könnte so aussehen:
---
name: change-review
description: Prüft eine gezielte Codeänderung auf mögliche Fehler und schlägt nachvollziehbare Tests vor.
---
# Codeänderung prüfen
Verwenden Sie diesen Ablauf, wenn eine konkrete Änderung oder ein begrenzter Diff geprüft werden soll.
1. Lesen Sie den Diff und identifizieren Sie die geänderten Dateien.
2. Prüfen Sie die Änderung auf Fehler, unbehandelte Randfälle und mögliche Sicherheitsprobleme.
3. Nennen Sie jede Beobachtung mit betroffener Datei und nachvollziehbarer Begründung.
4. Schlagen Sie passende Tests vor. Führen Sie keine nicht angeforderten Änderungen aus.
5. Wenn keine belastbare Beobachtung vorliegt, sagen Sie das ausdrücklich.
Das Beispiel ist eine Vorlage, kein Nachweis dafür, dass Claude Code jede Anweisung unter allen Umständen identisch ausführt. Der Name beschreibt den Zweck knapp; die Beschreibung nennt Tätigkeit und Einsatzbereich; der Text begrenzt den Umfang und macht das gewünschte Ergebnis überprüfbar. Ein Satz wie „Hilf beim Programmieren“ wäre zu allgemein. Er unterscheidet den Skill kaum von einer gewöhnlichen Anfrage und bietet wenig Orientierung für die automatische Auswahl.
Eine hilfreiche Beschreibung nennt die konkrete Tätigkeit und den passenden Anlass. Vermeiden Sie Versprechen, die der Inhalt nicht einlösen kann. Wenn ein Skill nur einen Diff untersucht, sollte seine Beschreibung nicht behaupten, er prüfe automatisch das gesamte Repository. Wenn Änderungen ausgeschlossen sind, muss die Anleitung das ausdrücklich sagen. Solche Grenzen helfen sowohl beim Aufruf als auch bei der Beurteilung eines unerwarteten Ergebnisses.
Beim Format kommt es auf gültiges YAML im Frontmatter und klar gegliederte Markdown-Anweisungen an. Achten Sie auf korrekt gesetzte Trennzeichen, passende Einrückungen und eine vollständige Datei. Zusätzliche Felder sollten Sie erst einsetzen, nachdem Sie ihre unterstützte Schreibweise und Wirkung in der aktuellen Dokumentation geprüft haben. Eine Sammlung veralteter Metadaten aus unterschiedlichen Beispielen erschwert die Fehlersuche und kann dazu führen, dass ein Skill anders funktioniert als beabsichtigt.
Behandeln Sie die Datei wie eine überprüfbare Arbeitsanweisung: Legen Sie fest, welche Eingabe erwartet wird, welche Schritte auszuführen sind und woran ein brauchbares Ergebnis erkennbar ist. Unklare Erwartungen lassen sich später nur schwer von einem Erkennungsproblem unterscheiden.
Die Abgrenzung zu anderen Projektanweisungen ist ebenfalls wichtig. Projektweite Hinweise und Erinnerungen können an anderer Stelle abgelegt werden; die Dokumentation zu Projektgedächtnis und Anweisungsdateien erläutert diesen Zusammenhang. Ein Skill sollte den wiederverwendbaren Ablauf enthalten und nicht unbesehen sämtliche allgemeinen Projektregeln duplizieren. Sonst entstehen widersprüchliche Anweisungen, deren Pflege bei Änderungen unnötig aufwendig wird.
Pfad, Dateiname und Ladebedingungen prüfen
>Vor dem ersten Aufruf lohnt sich eine systematische Prüfung. Kontrollieren Sie zuerst den vollständigen Pfad vom Projekt- oder Benutzerverzeichnis bis zu SKILL.md. Vergleichen Sie danach den Namen des Skill-Unterverzeichnisses mit dem Namen im Frontmatter, sofern Sie dort einen Namen angegeben haben. Die Spezifikation beschreibt gültige Namensregeln; halten Sie Namen kurz und konsistent, statt Leerzeichen, wechselnde Schreibweisen oder unnötige Sonderzeichen einzuführen.
Die Einstellungen von Claude Code können erklären, wie eine Installation konfiguriert ist. Prüfen Sie deshalb, ob ein abweichendes Arbeitsverzeichnis, eine projektbezogene Konfiguration oder eine Plugin-Einbindung die erwartete Ablage beeinflusst. Gehen Sie jedoch nicht davon aus, dass jede Einstellung ein alternatives Skill-Verzeichnis definiert: Übernehmen Sie dafür nur eine Option, die in der aktuellen Dokumentation ausdrücklich beschrieben ist.
Typische Fehlerquellen lassen sich in vier Gruppen ordnen:
- Falsche Verzeichnisebene: Der Skill-Ordner liegt außerhalb des unterstützten Projekt- oder Benutzerpfads.
- Falscher Dateiname: Die Datei heißt nicht exakt
SKILL.md, etwa weil eine zusätzliche Endung angehängt wurde. - Ungültiges Frontmatter: YAML-Trennzeichen, Einrückungen oder Feldwerte sind fehlerhaft.
- Unklare Beschreibung: Die Aufgabenbeschreibung passt nicht zum Testauftrag oder nennt den Anwendungsfall nicht.
Auch Zugriffsrechte und Projektkontext verdienen Aufmerksamkeit. Wenn Claude Code aus einem anderen Verzeichnis gestartet wird als erwartet, kann eine projektbezogene Ablage übersehen werden. Wenn ein Dateimanager Erweiterungen ausblendet, kann eine Datei scheinbar korrekt heißen, tatsächlich aber eine zusätzliche Endung besitzen. Öffnen Sie sie deshalb im Terminal oder prüfen Sie den vollständigen Dateinamen, statt sich allein auf die Anzeige im Dateimanager zu verlassen.
Was sollte vor dem Test der Skill-Erkennung geprüft werden?
Prüfen Sie Pfad, Ordnername, exakten Dateinamen und Frontmatter nacheinander. Ändern Sie zunächst nur einen fraglichen Punkt und testen Sie erneut. Werden mehrere Dinge gleichzeitig verändert, ist bei einem Erfolg nicht mehr klar, welche Korrektur entscheidend war. Notieren Sie für eine reproduzierbare Prüfung außerdem, aus welchem Projektverzeichnis Claude Code gestartet wurde.
Expliziter Aufruf und automatische Auswahl
>Ein expliziter Aufruf eignet sich, wenn Sie einen bestimmten Ablauf gezielt prüfen oder für eine Aufgabe bewusst wählen möchten. Ein Skill mit dem Namen change-review kann, abhängig von den aktuellen Regeln und der Installation, über einen passenden Slash-Aufruf wie /change-review angefordert werden. Prüfen Sie das in der aktuellen offiziellen Dokumentation zu Skills, bevor Sie daraus eine feste Teamregel machen. Die Verfügbarkeit hängt von der Skill-Konfiguration und den unterstützten Aufrufbedingungen ab.
Bei einer automatischen Auswahl ordnet Claude Code eine Anfrage anhand ihrer Beschreibung einem passenden Skill zu. Dafür muss die Beschreibung konkret genug sein, um den Anwendungsfall von allgemeinen Programmieraufgaben abzugrenzen. Automatische Auswahl und expliziter Aufruf sind daher nicht austauschbar: Der explizite Weg prüft, ob eine gezielte Anforderung funktioniert; der automatische Weg prüft zusätzlich, ob Beschreibung und Anfrage zusammenpassen. Eine ausbleibende automatische Auswahl beweist nicht, dass der Dateipfad ungültig ist.
Wie lässt sich ein Skill-Aufruf mit einem beobachtbaren Ergebnis testen?
Verwenden Sie zuerst eine konkrete, begrenzte Aufgabe, deren Ergebnis sich an den Anweisungen messen lässt. Beim Beispiel change-review kann der Auftrag lauten: „Prüfen Sie diese Änderung, nennen Sie mögliche Fehler mit Dateipfad und Begründung, schlagen Sie passende Tests vor und ändern Sie keine Dateien.“ Der Test ist aussagekräftig, wenn die Antwort die vereinbarten Bestandteile enthält und keine ausgeschlossene Änderung vornimmt. Das ist eine Beobachtung aus diesem Test, keine Garantie für spätere Anfragen.
Führen Sie für eine klare Prüfung zwei Durchgänge aus. Fordern Sie den Skill zuerst ausdrücklich an und halten Sie fest, ob die erwartete Art der Analyse erscheint. Stellen Sie anschließend eine ähnlich formulierte Aufgabe ohne Slash-Aufruf. So lässt sich getrennt beurteilen, ob der explizite Aufruf funktioniert und ob eine automatische Auswahl für diese Formulierung erfolgt. Verändern Sie dabei nicht gleichzeitig die Datei, die Beschreibung und die Testanfrage.
Ist das Ergebnis unvollständig, vergleichen Sie es mit den Arbeitsschritten in SKILL.md. Wenn die gewünschte Ausgabe nicht eindeutig beschrieben ist, verbessern Sie die Anweisung. Wird der Skill gar nicht erkannt, prüfen Sie zuerst Pfad und Metadaten. Bleibt das Verhalten nach einer Korrektur unverändert, prüfen Sie die aktuelle Ladeweise und wiederholen Sie den Test unter denselben Bedingungen, statt aus einer einzelnen Beobachtung eine allgemeine Versionsregel abzuleiten.
Fehlerbilder gezielt eingrenzen
>Bei einem Skill, der nicht auftaucht, führt die kürzeste Diagnose vom Dateisystem zur Anfrage: Ist die Datei vorhanden? Liegt sie in einem unterstützten Verzeichnis? Stimmt die Schreibweise? Ist das Frontmatter gültig? Passt die Beschreibung zur Aufgabe? Jede Antwort sollte überprüfbar sein. Notieren Sie beispielsweise den vollständigen Pfad und die genaue Testanfrage, damit eine weitere Person denselben Fall reproduzieren kann.
Wird der Skill explizit aufgerufen, aber nicht wie gewünscht ausgeführt, ist die wahrscheinlichste nächste Maßnahme eine präzisere Anleitung, nicht eine immer längere Beschreibung. Teilen Sie große Abläufe in klar erkennbare Schritte auf, formulieren Sie Grenzen eindeutig und benennen Sie das erwartete Ergebnis. Ergänzen Sie Beispiele nur, wenn sie einen wiederkehrenden Mehrdeutigkeitsfall erklären. Zu viele Sonderfälle können den Kernauftrag verdecken.
Wie ist ein nicht ausgelöster Skill einzuordnen?
Wenn der explizite Aufruf funktioniert, die automatische Auswahl aber nicht, prüfen Sie, ob die Beschreibung den Anlass und die Tätigkeit der tatsächlichen Anfrage abdeckt. Wenn auch der explizite Aufruf scheitert, kontrollieren Sie zuerst Verzeichnis und Dateiformat. Nach jeder Änderung wiederholen Sie denselben Test und halten fest, ob sich Erkennung, Inhalt oder beides geändert hat.
Für die Wahl des nächsten Schritts hilft diese Bedingungsliste:
- Wenn der Skill nur für ein Repository gelten soll, legen Sie ihn im unterstützten Projektbereich ab; andernfalls verwenden Sie die persönliche Ablage.
- Wenn der explizite Aufruf nicht funktioniert, kehren Sie zur Prüfung von Pfad, Dateiname und Frontmatter zurück, bevor Sie die Beschreibung umformulieren.
- Wenn der explizite Aufruf funktioniert, aber die automatische Auswahl ausbleibt, schärfen Sie die Aufgabenbeschreibung und testen Sie eine passende Anfrage erneut.
- Wenn Claude Code den Skill erkennt, aber Arbeitsschritte verfehlt, überarbeiten Sie die Ausführungsanweisungen und prüfen Sie das Ergebnis mit derselben Aufgabe.
- Wenn Teammitglieder den Ablauf gemeinsam pflegen müssen, bevorzugen Sie eine nachvollziehbare Projektablage gegenüber einer nur lokal vorhandenen persönlichen Konfiguration.
Ein Skill ist eine kleine, versionierbare Arbeitsanweisung, aber keine Garantie für identische Ergebnisse in jeder Sitzung. Für Teamabläufe sollten Sie daher neben der Datei auch die Testanfrage und das erwartete Verhalten dokumentieren. Bei sensiblen Quelltexten gehören Zugriffsrechte und Datenverarbeitung in die Prüfung; die Datenschutzhinweise sind ein sinnvoller Ausgangspunkt, wenn für spätere Entwicklungsarbeit eine externe Umgebung erwogen wird.
Der beste nächste Schritt ist, einen echten wiederkehrenden Vorgang aus dem eigenen Entwicklungsalltag auszuwählen, ihn mit einem engen Geltungsbereich in SKILL.md festzuhalten und expliziten sowie automatischen Aufruf getrennt zu testen. Für die meisten Skill-Aufgaben ist die lokale Projekt- oder Benutzerablage der einfachste Einstieg; ein entfernter Mac löst keine unklare Skill-Beschreibung und ist nicht automatisch die bessere Wahl. Lokale Entwicklung vermeidet Netzabhängigkeit und zusätzliche Übertragung, verlangt aber eigene Gerätepflege. Eine entfernte Umgebung bringt Netzwerk- und Zugriffsfragen mit sich und ist für dauerhaft intensive Arbeit oder zwingend benötigte physische Schnittstellen nicht immer passend. Wenn ein zeitlich begrenzter macOS-Entwicklungsplatz sinnvoll ist, können Sie die tatsächlichen Bedingungen für einen gemieteten Cloud-Mac von Zilmac mit Ihrem Arbeitsablauf abgleichen, bevor Sie Ihre Skills dort einsetzen.
- Claude-Code-Skills für den Alltag: Empfehlungen, Installation und Teamverwaltung
- Praxisbeispiel für einen spezialisierten Skill: Diagramme mit Claude Code erstellen
Richten Sie Ihre Entwicklungsumgebung auf einem Cloud-Mac von Zilmac ein
Nutzen Sie vollständiges macOS auf einem dedizierten Mac mini M4, um Ihre Entwicklungswerkzeuge und wiederkehrenden Abläufe flexibel auszuführen.
Verbinden Sie sich per SSH für die Arbeit im Terminal oder per VNC mit der grafischen macOS-Oberfläche. — Planoptionen anzeigen