Zum Inhalt springen
SONOYA.com
KI

Claude Code Skill selbst schreiben: SKILL.md erklärt

So schreibst Du einen eigenen Skill für Claude Code: Ordner, SKILL.md mit name und description, Skripte, Aufruf per /name und die häufigsten Fehler.

Von

Puzzleteil auf dunkelrotem Grund als Sinnbild für einen Skill, der Claude Code um eine eigene Fähigkeit erweitert

Wenn Du Claude Code immer wieder dieselbe Anleitung in den Chat kopierst, etwa wie Commit-Nachrichten in Deinem Projekt aussehen sollen oder welche Schritte vor einem Release nötig sind, gehört diese Anleitung in einen eigenen Skill. Ein Skill ist ein Ordner mit einer Datei SKILL.md, die Claude bei Bedarf lädt oder die Du mit /name direkt startest. Hier baust Du Schritt für Schritt einen vollständigen Skill, der Commit-Nachrichten im Stil Deines Projekts schreibt, und erfährst, woran es liegt, wenn Claude ihn nicht benutzt.

Die Anleitung folgt dem Stand der offiziellen Doku Extend Claude with skills vom November 2026. Das Prüfskript und die Frontmatter des Beispiels habe ich unter macOS mit Bash, git und einem YAML-Parser in einem leeren Test-Repository geprüft.

Wann ein Skill die richtige Wahl ist

Claude Code kennt mehrere Orte für Anweisungen, und jeder hat einen anderen Zweck. Der Unterschied liegt vor allem darin, wann der Inhalt geladen wird.

WerkzeugWofürWann es greift
CLAUDE.mdkurze Regeln und Fakten für jede Sitzungimmer, bei jedem Start
SkillAbläufe, Checklisten, NachschlagewissenBeschreibung immer, Inhalt nur bei Bedarf
HookRegeln, die ausnahmslos gelten müssenbei jedem passenden Ereignis, erzwungen
MCP-ServerZugriff auf fremde Systeme wie Datenbanken oder APIswenn Claude das Werkzeug aufruft

Ein Skill lohnt sich also, sobald aus einem Abschnitt Deiner CLAUDE.md ein Verfahren mit mehreren Schritten geworden ist. Claude sieht in jeder Sitzung nur Name und Beschreibung des Skills, der eigentliche Text kostet erst dann Kontext, wenn er gebraucht wird. Was dagegen in jede Sitzung gehört, erklärt der Artikel CLAUDE.md für Claude Code: was rein gehört, was nicht. Muss eine Regel immer greifen, auch wenn Claude sie vergisst, ist ein Hook die bessere Wahl, wie ihn Claude Code Hooks: Anleitung mit fünf Beispielen zeigt.

Die früheren eigenen Slash-Commands unter .claude/commands/ sind inzwischen in Skills aufgegangen. Alte Dateien dort funktionieren weiter, für Neues nimmst Du aber einen Skill, weil nur er weitere Dateien wie Skripte mitbringen kann.

Schritt 1: Den Speicherort festlegen

Wo der Skill-Ordner liegt, entscheidet, in welchen Sitzungen er verfügbar ist:

  • Persönlich: ~/.claude/skills/<name>/SKILL.md gilt für alle Deine Projekte auf diesem Rechner.
  • Projekt: .claude/skills/<name>/SKILL.md im Repository gilt für alle, die in diesem Projekt arbeiten, sobald Du den Ordner committest.
  • Plugin: Skills in einem Plugin erscheinen als /plugin-name:skill-name überall dort, wo das Plugin aktiv ist.

Für einen Skill, der den Stil eines bestimmten Projekts kennt, ist der Projektordner richtig. Wechsle in Dein Repository und leg den Ordner samt Unterordner für Skripte und Beispiele an:

Code
mkdir -p .claude/skills/commit-nachricht/scripts
mkdir -p .claude/skills/commit-nachricht/references

Der Ordnername commit-nachricht wird später zum Befehl /commit-nachricht. Halte Dich an Kleinbuchstaben, Ziffern und Bindestriche mit höchstens 64 Zeichen, denn das verlangt der offene Standard Agent Skills, dem Claude Code folgt. Dann funktioniert der Skill auch in anderen Werkzeugen und beim Hochladen zu claude.ai.

Schritt 2: Die SKILL.md schreiben

Jede SKILL.md besteht aus zwei Teilen: einer YAML-Frontmatter zwischen zwei Zeilen mit --- und darunter den Anweisungen in Markdown. Öffne die Datei im Editor, zum Beispiel mit nano .claude/skills/commit-nachricht/SKILL.md, und füge diesen Inhalt ein:

Code
---
name: commit-nachricht
description: Schreibt eine Commit-Nachricht im Stil dieses Projekts aus den vorgemerkten Änderungen. Nutzen, wenn der User eine Commit-Nachricht, einen Commit-Text oder eine Beschreibung seiner Änderungen für git haben will.
allowed-tools: Bash(git diff *) Bash(git log *) Bash(${CLAUDE_SKILL_DIR}/scripts/betreff-pruefen.sh *)
---

## Vorgemerkte Änderungen

!`git diff --staged`

## Aufgabe

Schreib aus den Änderungen oben eine Commit-Nachricht nach diesen Regeln:

1. Ist der Diff leer, sag, dass nichts vorgemerkt ist, und hör auf.
2. Lies mit `git log --oneline -15` die letzten Betreffzeilen und übernimm ihren Stil.
3. Betreff auf Deutsch, höchstens 72 Zeichen, ohne Punkt am Ende, beschreibt das Ergebnis.
4. Danach eine Leerzeile und zwei bis vier Zeilen, die das Warum erklären.
5. Prüf den Betreff mit `${CLAUDE_SKILL_DIR}/scripts/betreff-pruefen.sh "<Betreff>"` und korrigiere ihn, bis das Skript „ok“ meldet.
6. Gib nur die fertige Nachricht in einem Codeblock aus. Committe nicht selbst.

Beispiele für gute Nachrichten stehen in [references/beispiele.md](references/beispiele.md). Lies sie, wenn Du unsicher bist, wie ausführlich der Text sein soll.

Speichere mit Strg + O, bestätige mit Enter und schließe nano mit Strg + X.

Die Frontmatter ist der wichtigste Teil, deshalb hier die drei Felder im Einzelnen:

  • name legt den Befehl fest. Fehlt das Feld, nimmt Claude Code den Ordnernamen. Beides sollte übereinstimmen.
  • description sagt, was der Skill tut und wann er passt. Claude Code lädt diese Beschreibung in jede Sitzung, und nur anhand dieses Textes entscheidet Claude, ob der Skill zu Deiner Anfrage gehört. Nenn deshalb die Wörter, die Du tatsächlich tippen würdest, und stell den wichtigsten Anwendungsfall an den Anfang, denn Claude Code kürzt die Beschreibung in der Übersicht nach 1.536 Zeichen.
  • allowed-tools erlaubt die aufgeführten Befehle ohne Rückfrage, solange der Skill in der aktuellen Runde läuft. Mit Deiner nächsten Nachricht erlischt die Freigabe wieder.

Die Zeile mit !`git diff --staged` ist eine Besonderheit von Claude Code: Der Befehl läuft, bevor Claude den Skill liest, und seine Ausgabe ersetzt die Zeile. Claude bekommt also gleich den echten Diff zu sehen und muss nicht raten. ${CLAUDE_SKILL_DIR} steht für den Ordner, in dem die SKILL.md liegt, damit das Skript unabhängig vom aktuellen Verzeichnis gefunden wird.

Die Doku kennt noch weitere Felder, etwa disable-model-invocation, context: fork für einen eigenen Subagenten oder paths, um den Skill auf bestimmte Dateien zu beschränken. Für den Anfang reichen die drei gezeigten völlig.

Schritt 3: Skript und Beispiele dazulegen

Ein Skill darf weitere Dateien enthalten, und genau das hält die SKILL.md schlank. Claude liest eine Datei aus references/ nur, wenn die Anleitung darauf verweist und sie gerade gebraucht wird. Ein Skript in scripts/ wird ausgeführt, sein Quelltext landet gar nicht erst im Kontext. Dieses Prinzip heißt in der Doku progressive Offenlegung: erst die Beschreibung, dann die Anleitung, dann bei Bedarf die Details.

Leg das Prüfskript mit nano .claude/skills/commit-nachricht/scripts/betreff-pruefen.sh an:

Code
#!/usr/bin/env bash
# Prüft die erste Zeile einer Commit-Nachricht.
betreff="$1"
laenge=${#betreff}
if [ "$laenge" -gt 72 ]; then
  echo "Zu lang: $laenge Zeichen (erlaubt sind 72)."
  exit 1
fi
if [[ "$betreff" == *. ]]; then
  echo "Bitte ohne Punkt am Ende."
  exit 1
fi
echo "Betreff ok ($laenge Zeichen)."

Mach das Skript ausführbar und probier es einmal von Hand aus:

Code
chmod +x .claude/skills/commit-nachricht/scripts/betreff-pruefen.sh
.claude/skills/commit-nachricht/scripts/betreff-pruefen.sh "Login-Formular: Fehlermeldung bei leerem Passwort ergänzt"

Die Ausgabe lautet Betreff ok (58 Zeichen). Ein Betreff mit Punkt am Ende oder mit mehr als 72 Zeichen liefert stattdessen einen Hinweis und den Exit-Code 1, und genau daran erkennt Claude, dass es nachbessern muss.

Zum Schluss legst Du mit nano .claude/skills/commit-nachricht/references/beispiele.md zwei oder drei echte Commit-Nachrichten aus Deinem Projekt ab, die Du gelungen findest. Ein paar gute Beispiele bringen Claude oft weiter als lange Regeln. Wie weit sich das Auslagern treiben lässt, zeigt book-to-skill: Fachbücher für Claude Code nutzbar machen: Dort liegt ein ganzes Fachbuch als eine Datei pro Kapitel neben der SKILL.md, und Claude lädt nur das Kapitel, das es gerade braucht. Der fertige Skill sieht dann so aus:

Code
.claude/skills/commit-nachricht/
├── SKILL.md
├── references/
│   └── beispiele.md
└── scripts/
    └── betreff-pruefen.sh

Schritt 4: Den Skill aufrufen und testen

Starte Claude Code im Projektordner mit claude. Neue oder geänderte Skills erkennt Claude Code auch in einer laufenden Sitzung, ein Neustart ist nur nötig, wenn der Ordner .claude/skills/ beim Start noch gar nicht existierte. Dann holt /reload-skills ihn nach.

Merk eine kleine Änderung mit git add vor und teste den Skill auf zwei Wegen. Direkt startest Du ihn, indem Du den Namen an den Anfang Deiner Nachricht setzt:

Code
/commit-nachricht

Für den automatischen Weg schreibst Du einfach eine passende Bitte wie „Schreib mir eine Commit-Nachricht für meine Änderungen“. Claude erkennt anhand der Beschreibung, dass der Skill passt, und lädt ihn. In beiden Fällen bekommst Du eine fertige Nachricht im Codeblock, deren Betreff das Prüfskript bestanden hat.

Soll Claude einen Skill nie von sich aus starten, etwa weil er etwas veröffentlicht oder deployt, ergänzt Du in der Frontmatter disable-model-invocation: true. Dann läuft er nur, wenn Du /name selbst tippst. Der umgekehrte Fall ist user-invocable: false für reines Hintergrundwissen, das Claude nutzen soll, das als Befehl aber keinen Sinn ergibt.

Wenn der Skill nicht greift: die typischen Fehler

Claude benutzt den Skill nicht. Fast immer ist die Beschreibung zu vage. „Hilft bei git“ passt auf hundert Anfragen und auf keine richtig. Schreib hinein, was der Skill tut und bei welchen Formulierungen er gemeint ist. Frag Claude außerdem „Welche Skills hast Du?“: Taucht Deiner in der Liste nicht auf, liegt er im falschen Ordner, oder der Ordnername enthält unzulässige Zeichen.

/commit-nachricht funktioniert, der automatische Aufruf aber nicht. Dann lässt sich die Frontmatter vermutlich nicht als YAML lesen, etwa wegen eines Doppelpunkts mit folgendem Leerzeichen mitten in der Beschreibung. Claude Code lädt den Skill in diesem Fall ohne Metadaten. Setz die Beschreibung in Anführungszeichen und prüf die Datei mit claude plugin validate .claude/skills, das meldet Frontmatter, die sich nicht lesen lässt. Achte auch darauf, dass --- wirklich in der allerersten Zeile steht.

Der Aufruf bricht mit „Shell command failed“ ab. Ein Befehl in einer !`…`-Zeile ist mit einem Fehlercode beendet worden, und damit scheitert der ganze Skill. Beim Testen fiel das bei git log auf, das in einem Repository ohne ersten Commit mit Code 128 endet und den Skill dort abbrechen würde. Deshalb steht git log im Beispiel als Anweisung im Text und nicht als vorab ausgeführter Befehl. Außerhalb des Auto-Modus bricht der Aufruf außerdem ab, wenn für einen vorab ausgeführten Befehl keine Freigabe besteht. Genau dafür steht er unter allowed-tools.

Claude hält sich nach einer Weile nicht mehr an den Skill. Der Inhalt wird beim Aufruf einmal in die Unterhaltung geladen und danach nicht neu gelesen. Nach einem /compact behält Claude Code nur den Anfang jedes Skills. Stell die wichtigsten Regeln deshalb nach oben und formuliere sie als dauerhafte Regel, nicht als einmaligen Schritt. Mehr dazu, was beim Verdichten mit dem Kontext passiert, steht in Claude Code: Kontext, /compact, /clear und Subagents.

Der Skill ist zu lang. Die Doku empfiehlt, die SKILL.md unter 500 Zeilen zu halten. Alles darüber gehört in Dateien unter references/, auf die Du in der Anleitung mit einem Satz verweist, wann Claude sie lesen soll.

Fazit

Ein guter Skill ist klein: eine präzise Beschreibung, eine kurze Anleitung in Schritten und ausgelagerte Details, die Claude nur bei Bedarf liest. Die Beschreibung verdient die meiste Sorgfalt, weil sie allein darüber entscheidet, ob Claude den Skill überhaupt findet. Fang mit einer Aufgabe an, die Du ohnehin jede Woche erklärst, teste sie mit /name und mit einer freien Formulierung, und schärf die Beschreibung nach, bis beides zuverlässig klappt.

Wenn Du Deine Skills auch in OpenAI Codex nutzen willst, zeigt Claude Code Skills in Codex nutzen, wie der zweite Agent dieselben Ordner mitliest. Und braucht Dein Skill Zugriff auf ein fremdes System, etwa eine Datenbank oder ein Ticketsystem, ergänzt Du ihn mit einem Werkzeug aus MCP-Server in Claude Code und Codex einrichten.

Weiterlesen.