So erstellen Sie einen Claude Code Skill, der wirklich funktioniert (Vollständiger Leitfaden)

Du hast Claude eine Woche lang benutzt und tippst immer wieder dasselbe. Jedes Mal, wenn du Code committest, fügst du die gleichen drei Regeln zu deinem Commit-Format ein. Jedes Mal, wenn du ein Dokument schreibst, erklärst du deinen Stil neu. Claude macht das gut, aber vergisst es, sobald der Chat endet – und morgen tippst du alles wieder von vorne.

Ein Skill behebt das. Es ist ein kleiner Ordner, den du einmal schreibst und der Claude dauerhaft einen Workflow beibringt, sodass er ihn in jeder Sitzung anwendet, ohne dass du ihn bitten musst.

So funktioniert es auf den Punkt gebracht: Ein Skill ist ein Ordner mit einer Datei darin. Claude behält stets eine einzeilige Zusammenfassung im Blick und lädt die vollständigen Anweisungen nur dann, wenn deine Anfrage dazu passt. Das ist der gesamte Mechanismus.

In dieser Anleitung erstellen wir einen echten Skill von Grund auf: commit-messages, der Git-Commits in deinem exakten Format schreibt. Wenn Claude installiert ist und sonst nichts, kannst du jeden Schritt mitgehen.

Was du am Ende haben wirst

Im Kern ist ein Skill ein Ordner mit einer erforderlichen Datei, SKILL.md. Drei optionale Ordner kommen später hinzu, wenn der Skill wächst:

1your-skill-name/
2├── SKILL.md          # Erforderlich – die Haupt-Skill-Datei
3├── scripts/          # Optional – ausführbarer Code
4├── references/       # Optional – Dokumentation
5└── assets/           # Optional – Vorlagen usw.

SKILL.md selbst besteht aus zwei Teilen: einem kurzen Header, der Claude mitteilt, wann der Skill verwendet werden soll, und darunter Anweisungen, die Claude sagen, was zu tun ist. Der Grund für diese Trennung ist wichtig. Claude liest den Header ständig, weiß also immer, dass der Skill existiert, lädt die Anweisungen aber nur, wenn deine Anfrage dazu passt. Behalte diese Unterscheidung im Hinterkopf, denn fast alles Weitere in dieser Anleitung ergibt sich daraus.

Erstelle ihn

Skills leben in einem Ordner namens .claude/skills in deinem Home-Verzeichnis, den sowohl Claude Code als auch die Desktop-App lesen. Er ist versteckt und existiert wahrscheinlich noch nicht, daher ist der schnellste Weg, ihn zusammen mit dem Ordner deines Skills zu erstellen, ein einzelner Befehl.

Auf dem Mac öffnest du das Terminal und führst Folgendes aus:

1mkdir -p ~/.claude/skills/your-skill-name

Unter Windows öffnest du PowerShell und führst Folgendes aus:

1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"

Der Ordnername ist nicht nur zur Dekoration. Claude verwendet ihn als Identifikator des Skills, und eine Formatierungsregel sorgt häufiger für Verwirrung als jede andere:

• Verwende Kebab-Schreibweise: notion-project-setup ✔
• Keine Leerzeichen: Notion Project Setup ✖
• Keine Unterstriche: notion_project_setup ✖
• Keine Großbuchstaben: NotionProjectSetup ✖

Erstelle in diesem Ordner eine Datei mit dem genauen Namen SKILL.md und öffne sie in einem beliebigen Texteditor. Alles, was jetzt kommt, kommt in diese Datei.

Entwirf ihn, bevor du ihn schreibst

Die Skills, die funktionieren, beginnen mit zwei Entscheidungen, die du triffst, bevor du eine Zeile der Datei schreibst. Beide fühlen sich überspringbar an, und keine ist es.

Erstens: Entscheide genau, wann der Skill ausgelöst werden soll. Schreibe zwei oder drei reale Situationen in den Worten, die ein Benutzer tatsächlich tippen würde:

• "diese Änderungen committen"
• "eine Commit-Nachricht für diesen Diff schreiben"
• "stagen und committen"

Das ist keine Beschäftigungstherapie. Diese Phrasen werden später zum Rohmaterial für deine Beschreibung und deine Tests, und ein Skill, der ohne sie entworfen wird, ist tendenziell genau in der Weise vage, die verhindert, dass er jemals ausgelöst wird.

Zweitens: Entscheide, woran du erkennen wirst, dass er funktioniert. Das wichtigste Kriterium ist, ob der Skill von selbst lädt, ohne dass du ihn benennst. Wenn du ihn jedes Mal manuell aufrufen musst, läuft der Skill zwar technisch, hat aber seine eigentliche Aufgabe verfehlt. Beobachte außerdem: ob er die Aufgabe beendet, ohne dass du ihn zwischendurch korrigieren musst, und ob er dir über verschiedene Sitzungen hinweg die gleiche Form von Ergebnis liefert.

Die Beschreibung macht oder bricht ihn

Von allem in der Datei leistet die Beschreibung im Header die meiste Arbeit, denn sie ist der einzige Teil, den Claude liest, wenn er entscheidet, ob der Skill überhaupt geladen wird. Deine Anweisungen könnten makellos sein, und es wäre egal, da Claude nie zu ihnen gelangt, wenn die Beschreibung nicht passt. Hier scheitern die meisten Skills, die "nicht funktionieren".

Eine gute Beschreibung beantwortet zwei Fragen in einem Satz: Was der Skill tut und wann Claude ihn einsetzen soll. Die zweite Hälfte ist die, die die Leute weglassen.

Hier ist der Unterschied:

1# schwach – sagt, was es ist, gibt Claude nichts, um eine Anfrage zuzuordnen
2description: Hilft bei Git-Commits.
3
4# stark – benennt die Momente, in denen er ausgelöst werden soll
5description: Schreibt Git-Commit-Nachrichten im Conventional Commits-Format. Verwende diesen Skill, wenn der Benutzer darum bittet, Änderungen zu committen, eine Commit-Nachricht zu schreiben oder Dateien zu stagen und zu committen.

Die schwache Version sagt Claude, dass der Skill existiert, verbindet ihn aber nie mit etwas, das du sagen würdest. Die starke Version benennt die tatsächlichen Phrasen, sodass Claude, wenn du "diese Änderungen committen" tippst, etwas zum Abgleichen hat. Verwende die Wörter, die ein Benutzer tatsächlich verwenden würde, halte das Ganze unter 1024 Zeichen und setze kein < oder > hinein.

Wenn ein Skill nicht auslöst, liegt die Lösung fast immer hier. Füge die Formulierungen hinzu, die du tatsächlich verwendest. Wenn du "meine Arbeit speichern" sagst, die Beschreibung aber nur "committen" erwähnt, hat Claude keine Möglichkeit, beides zu verknüpfen. Und wenn das Gegenteil passiert und der Skill auslöst, obwohl er es nicht sollte, grenze die Beschreibung ein oder füge einen negativen Auslöser hinzu:

1description: Schreibt Git-Commit-Nachrichten im Conventional Commits-Format. Verwende diesen Skill beim Committen von Änderungen. Nicht verwenden für das Schreiben von Code-Kommentaren oder Dokumentation.

Es gibt eine schnelle Methode, um deine Arbeit zu überprüfen, bevor du dich darauf verlässt. Frage Claude direkt:

"Wann würdest du den Skill commit-messages verwenden?"

Claude wird deine Beschreibung in seinen eigenen Worten wiedergeben. Wenn das nicht mit dem Zeitpunkt übereinstimmt, zu dem der Skill tatsächlich auslösen soll, hast du dein Problem gefunden, und es liegt in der Beschreibung, nicht in den darunterliegenden Anweisungen.

Schreibe Anweisungen, die Claude auch tatsächlich befolgt

Unter dem Header kommt der Hauptteil in einfachem Markdown. Hier lebt dein eigentlicher Workflow, und zwei Gewohnheiten trennen Anweisungen, die Claude befolgt, von denen, die er stillschweigend ignoriert.

Die erste ist Präzision. Claude handelt nach konkreten Anweisungen und übergeht vage, also je genauer du bist, desto zuverlässiger verhält er sich:

1# Schlecht
2Validiere den Commit, bevor du ihn abschließt.
3
4# Gut
5Führe `python scripts/validate.py "<message>"` aus.
6Wenn es fehlschlägt, behebe Folgendes:
7- Ungültiger Typ: verwende feat, fix, docs, refactor, test, chore
8- Zusammenfassung über 60 Zeichen: kürzen

Die zweite ist die Reihenfolge. Claude gewichtet das, was er zuerst liest, also wird eine Regel, die am Ende einer langen Datei vergraben ist, oft übersehen. Setze alles, was nicht gebrochen werden darf, ganz oben unter eine Überschrift, die darauf hinweist:

1## Wichtig
2- Zusammenfassungszeile unter 60 Zeichen, immer
3- Nur Präsens: "hinzufügen", nicht "hinzugefügt"

Es gibt auch eine Grenze dessen, was Sprache garantieren kann. Anweisungen werden interpretiert, was bedeutet, dass Claude sie gut befolgt, aber nicht jedes Mal identisch. Wenn eine Prüfung bei jedem Durchlauf unbedingt bestehen muss, beschreibe sie nicht in Prosa, sondern verschiebe sie in ein Skript und lasse die Anweisungen es ausführen. Code macht jedes Mal dasselbe; ein Satz nicht. (Dafür ist der Ordner scripts/ da, mehr dazu im nächsten Abschnitt.)

Eine Struktur, die sich über die meisten Skills hinweg bewährt hat, sieht so aus:

1# Skill-Name
2
3## Wichtig
4Kritische Regeln, die nicht übersehen werden dürfen.
5
6## Anweisungen
7Schritt für Schritt, spezifisch und umsetzbar.
8
9## Beispiele
10Konkrete Eingabe und Ausgabe. Claude kopiert Beispiele zuverlässiger, als es Regeln befolgt.

Halte die Datei schlank. Sobald sie beginnt, über ihre Kernanweisungen hinauszuwachsen, ist es Zeit, die zusätzlichen Details auszulagern – genau dafür sind die optionalen Ordner da.

Skripte, Referenzen, Assets

Bisher haben wir einen Skill, der Claude Anweisungen gibt. Die drei optionalen Ordner verwandeln ihn in einen Skill, der Claude Werkzeuge an die Hand gibt, und hier kann ein Skill Dinge tun, die ein einfacher Prompt nicht kann.

scripts/ enthält Code, den Claude ausführt, für alles, was exakt sein muss. Statt darauf zu vertrauen, dass Claude mit bloßem Auge erkennt, ob ein Commit richtig formatiert ist, übergibst du ihm ein Skript, das prüft:

1# scripts/validate.py
2import sys
3msg = sys.argv[1]
4types = ("feat", "fix", "docs", "refactor", "test", "chore")
5
6if msg.split(":")[0] not in types:
7    print(f"Ungültiger Typ. Verwende: {', '.join(types)}")
8elif len(msg.split("\n")[0]) > 60:
9    print("Zusammenfassung zu lang (über 60 Zeichen)")
10else:
11    print("OK")

Dann weist du Claude an, es in SKILL.md zu verwenden:

1Führe vor dem Abschluss `python scripts/validate.py "<message>"` aus
2und behebe alles, was es beanstandet.

Jetzt wird die Formatierungsregel durch Code erzwungen, der jedes Mal gleich läuft, anstatt darauf angewiesen zu sein, dass Claude sich ans Überprüfen erinnert.

references/ enthält Dokumentation, die nur bei Bedarf geladen wird. Angenommen, deine Commit-Konventionen umfassen zwei Seiten mit Scopes, Fußzeilen und Randfällen. Packe das alles in SKILL.md und es wird bei jedem einzelnen Commit geladen, selbst bei einem Einzeiler. Verschiebe es stattdessen in eine Referenzdatei:

1your-skill-name/
2├── SKILL.md
3└── references/
4    └── conventions.md

Und verweise von der Hauptdatei darauf:

1Die vollständige Konventionsliste findest du unter references/conventions.md

Claude öffnet diese Datei nur, wenn die Aufgabe es erfordert. Das ist der ganze Grund, warum Skills günstig im Betrieb bleiben: Die schweren Details liegen auf der Platte, bis sie wirklich relevant sind, anstatt bei jeder Gelegenheit im Kontext mitzureisen.

assets/ enthält Dateien, die der Skill in seiner Ausgabe verwendet, statt sie als Anleitung zu lesen, wie eine Vorlage, eine Konfigurationsdatei oder ein Logo. Ein Commit-Skill braucht keine, aber ein Skill, der Berichte generiert, könnte hier eine template.md bereithalten und sie jedes Mal ausfüllen, sodass jeder Bericht die gleiche Struktur hat.

Zusammengenommen sind diese drei Ordner der Unterschied zwischen einem Skill, der Claude sagt, wie du arbeitest, und einem, der Claude die genauen Werkzeuge an die Hand gibt, um die Arbeit auf deine Art zu erledigen.

Das Einzige, woran du dich erinnern solltest

Ein Skill bringt Claude keine neue Fähigkeit bei. Er weiß bereits, wie man einen Commit schreibt. Was der Skill tut, ist, ihn dazu zu bringen, die Aufgabe jedes Mal auf deine Art zu erledigen, ohne dass du es wiederholen musst.

Und wenn ein Skill nicht funktioniert, liegt die Ursache fast nie an den Anweisungen, über die du gebrütet hast. Es ist die Beschreibung. Claude entscheidet, ob der Skill geladen wird, anhand dieser einen Zeile, bevor er jemals die Arbeit darunter liest. Wenn die Beschreibung stimmt, wird endlich alles darunter genutzt.

Falls das hilfreich war, schau auf mein Profil und folge mir. Ich schreibe über Technik, KI und Systeme, die wirklich laufen.

Ciao,

@undefinedKi