Claude Code hat meinen Skill 5 Mal ignoriert. 1 Zeile hat's gefixt

Ein Claude-Code-Skill kann einwandfrei laufen, wenn du ihn beim Namen aufrufst, und sich trotzdem nie von selbst laden. Unserer lief jedes Mal, wenn wir seinen Namen tippten, und wurde jedes Mal übergangen, wenn wir dieselbe Aufgabe in normalen Worten stellten. Wir haben zugesehen, wie er übergangen wird, haben gelesen, warum, und die eine Zeile umgeschrieben, die es behoben hat.

Ein Skill ist ein gespeicherter Satz Anweisungen, den Claude Code von selbst aufgreift, wenn deine Anfrage dazu passt. Über den Treffer entscheidet eine Zeile, die Claude vor der Auswahl liest, und das sind nicht deine Anweisungen. Die sechs Schritte unten führen dich vom Prompt, den du ständig neu tippst, zu einem Skill, der sich von selbst lädt, plus einem Test mit zwanzig Anfragen, der einen übergangenen Skill findet, bevor es dein Team tut.

Test (gleiche Anfrage, frische Sitzungen)	Skill geladen
Per Namen aufgerufen (/release-notes)	2 von 2
Normale Worte, ursprüngliche Beschreibung	0 von 5
Normale Worte, umgeschriebene Beschreibung	5 von 5

Ein Skill ist ein Ordner mit einer einzigen Datei darin, SKILL.md. Die Datei beginnt mit einem kurzen Header (ein Name und eine Beschreibung in einem Satz), gefolgt von den Anweisungen. Er funktioniert wie eine Funktion: Der Aufrufer liest die Signatur und den Docstring, und der Rumpf läuft erst, wenn er aufgerufen wird. Lege ihn in deinem Home-Ordner ab, um ihn in jedem Projekt zu haben, oder im Repository, damit jeder, der dort arbeitet, ihn bekommt.

Fang bei der Aufgabe an, nicht bei der Datei. Nimm den Prompt, den du ständig neu tippst, und schreib die genaue Ausgabe auf, die du willst. Unserer waren wöchentliche Release Notes: die Commits seit Montag, nach Bereich gruppiert, Chores weggelassen, eine Zeile pro Änderung mit der Nummer des Pull Requests. Im Open-Source-Repository von Hono lieferte dieser lange Prompt saubere Notes für acht Bugfixes der Woche, und diese Ausgabe wurde das Ziel, das der Skill treffen musste.

Nicht jeder Prompt verdient einen Skill. Eine einmalige Frage nicht, und ein Skill, den du nie wiederverwendest, ist nur eine weitere Zeile, die Claude lesen muss. Führe eine kurze Liste der Prompts, die du jede Woche tippst; der oberste wird dein erster Skill.

Lege .claude/skills/release-notes/SKILL.md in deinem Projekt an: ein Ordner skills im versteckten Ordner .claude, ein Ordner mit dem Namen des Skills und darin die Skill-Datei. Der Ordner ist wichtig. Eine lose release-notes.md lädt gar nicht, und die Docs nennen das als Erstes zum Prüfen.

Der Header besteht aus ein paar beschrifteten Zeilen zwischen zwei Strichreihen und muss in der ersten Zeile der Datei beginnen, sonst ignoriert ihn Claude Code. Unserer hatte einen Namen, release-notes, und die Beschreibung, die die meisten schreiben würden:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Unter den Header kommen die Anweisungen als nummerierte Schritte, so wie du sie einem neuen Teammitglied geben würdest. Unser Skill hat fünf: die Commits seit Montag finden, chore- und docs-Commits weglassen, nach Conventional-Commit-Scope gruppieren, pro Änderung eine schlichte Zeile schreiben und einen betitelten Block mit kurzer Zusammenfassung oben ausgeben. Anthropic empfiehlt, diesen Teil kurz zu halten. Ein Neustart ist nicht nötig: Claude Code übernimmt einen neuen oder geänderten Skill in der Sitzung, in der du schon bist.

Teste ihn per Namen: Tippe einen Schrägstrich, wähle den Skill im Menü, drücke Enter. In frischen Sitzungen las unserer das Commit-Log, gruppierte die Fixes nach Bereich und schrieb die Notes genau wie gewünscht, jedes Mal. Der Haken: Du und alle in deinem Team müsst sich seinen Namen merken.

Ein Teammitglied wird den Namen des Skills nicht tippen. Es öffnet eine neue Sitzung und fragt so, wie es dich fragen würde. Teste also genau das: Öffne eine frische Sitzung (eine neue Unterhaltung, in der nichts geladen ist) und bitte in deinen eigenen Worten um die Aufgabe. Sie muss frisch sein, denn ein bereits benutzter Skill bleibt in der Unterhaltung, und ein Test in dieser Sitzung beweist nichts.

Wir tippten „what did we ship this week?“. Claude führte das Commit-Log selbst aus und schrieb auf seine Art eine Zusammenfassung, ohne Spur des Skills. Die Antworten waren nicht schlecht, aber sie schwankten von Lauf zu Lauf: Einmal wurde ab Montag gezählt, ein anderes Mal ab dem letzten Release-Tag, und eine Docs-Änderung kam hinein, die der Skill weggelassen hätte. In fünf frischen Sitzungen wurde der Skill in allen fünf übergangen.

Fünf Läufe sind eine Demo, keine Statistik. Aber ein Skill, der per Namen funktioniert und in normalen Worten jedes Mal übergangen wird, macht seinen Job nicht, und da er den Namenstest in Schritt zwei bestanden hat, käme man nie auf die Idee, nachzusehen.

Bevor du ein Wort änderst, mach drei Prüfungen:

1. /skills listet jeden Skill auf, den die Sitzung sieht. Suche deinen. Unserer war gelistet und aktiv, aber das Setup enthielt 277 Skills, und mehrere Plugin-Skills passten auf „release“ vor unserem.
2. claude --debug schreibt ein detailliertes Log darüber, was Claude Code lädt. Such die Zeilen zu den Skills. Bei uns war der Projekt-Skill geladen, dazu eine Warnung, dass die Skill-Liste das Budget überschreitet und deshalb einige Beschreibungen gekürzt werden.
3. claude plugin validate .claude/skills prüft, ob der Header wohlgeformt ist. Das ist wichtig: Ein kaputter Header lässt den Skill per Namen weiter laufen, aber Claude kann ihn nicht mehr von selbst zuordnen. Unserer bestand.

Prüfung	Was sie dir sagt	Unser Ergebnis
/skills	Ist der Skill sichtbar und aktiv?	Gelistet, aktiv (277 Skills)
--debug	Wurde er geladen? Ist die Liste gekürzt?	Geladen; Warnung: Liste über Budget
plugin validate	Lässt sich der Header lesen?	Bestanden

Mit geladener Datei und gültigem Header liegt die Ursache an der Beschreibung. Bis es entscheidet, einen Skill zu laden, liest Claude deine Anweisungen nicht. Es liest pro Skill eine Zeile, den Namen und die Beschreibung, und gleicht sie mit deinen Worten ab. Unsere sagte „generates changelog documents from repository history“; die Anfrage sagte „what did we ship this week“. Die beiden Sätze teilen kein Wort. Claude hat nie unsere Anweisungen gelesen; es las eine Zeile, und diese Zeile benutzte nicht unsere Worte.

Die Budget-Warnung heißt: Claude Code kürzt Beschreibungen, damit alles passt, zuerst die am wenigsten genutzten Skills, und ein brandneuer Skill ist der am wenigsten genutzte von allen. Prüf, ob deiner überlebt hat: Unserer ja, denn Anfragen mit seinen eigenen Worten luden ihn weiterhin.

Schreib die Beschreibung für den Moment, in dem jemand fragt, nicht für die Datei. Sag, was der Skill tut, wann man ihn nutzt, und welche Worte die Leute wirklich tippen. Unsere wurde:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Anthropics Authoring-Guide fügt eine Regel hinzu: in der dritten Person schreiben („Writes“), nie „I can help“ oder „You can use this“.

Beweis das dann in einer frischen Sitzung mit derselben Anfrage. „What did we ship this week?“ lud den Skill jetzt, bevor Claude irgendetwas anfasste, und die Notes kamen in unserem Format, in fünf von fünf frischen Sitzungen.

Mach auch eine Baseline: Schalte den Skill mit einem Skill-Override in deiner lokalen Settings-Datei aus (das blendet ihn aus, ohne ihn zu löschen). Ausgeschaltet kehrte Claude zu seiner eigenen Zusammenfassung zurück; eingeschaltet lud sich der Skill. Der Skill machte den Unterschied, nicht der Zufall.

Die Grenze: Eine Beschreibung, die auf zu viel passt, lässt den Skill dort feuern, wo er es nicht soll. Füge die Worte hinzu, die du wirklich benutzt, nicht jedes Wort, das dir einfällt.

Eine Anfrage hat den Fix bewiesen; ein Skill, auf den sich ein Team verlässt, wird auf viele Arten angefragt. Anthropics skill-creator beschreibt den Test: zwanzig Anfragen, eine Mischung aus solchen, die den Skill laden sollen, und Beinahe-Treffern, die es nicht sollen. Ein Beinahe-Treffer klingt ähnlich, ist aber eine andere Aufgabe, etwa „write a commit message for my staged changes“. Führe jede Anfrage in einer eigenen frischen Sitzung aus und notiere, ob der Skill geladen wurde. Das eigene Skript des skill-creator sah den Skill auf unserer Claude-Code-Version nicht, also ließen wir dieselben zwanzig Anfragen mit einem kurzen eigenen Skript laufen.

Beschreibung	Anfragen, die ihn laden sollten und es taten	Beinahe-Treffer, die ihn luden
Original	4 von 10	0 von 10
Umgeschrieben	10 von 10	0 von 10

Vor dem Umschreiben lud sich der Skill nur bei Anfragen, die schon „release notes“, „changelog“ oder „release“ enthielten: das Wort-Matching aus Schritt vier, offen sichtbar. Nach dem Umschreiben lud er bei jeder Anfrage, bei der er laden sollte, und blieb trotzdem aus jedem Beinahe-Treffer heraus.

Bei einem Skill, der nie fehlen darf, erzwingst du ihn. Tippe seinen Namen oder füge einen Hook hinzu (ein kleines Skript, das Claude Code zu einem festen Zeitpunkt ausführt, hier bei jeder Nachricht, die du sendest), dessen Ausgabe Claude anweist, für diese Aufgabe den Skill zu nutzen. Mit dem Hook lud sogar die ursprüngliche Beschreibung bei der normalen Anfrage. Die Grenze: Jeder Testlauf kostet echtes Kontingent, und ein Hook fügt jeder Nachricht eine Zeile hinzu, also heb ihn für die wenigen Skills auf, die wirklich feuern müssen. Lass deine Liste erneut laufen, wann immer du die Beschreibung änderst.

Unser Release-Notes-Skill funktionierte per Namen jedes Mal, wurde in jeder frischen Sitzung in normalen Worten übergangen, und eine umgeschriebene Zeile ließ ihn jedes Mal laden. Der Grund: Claude liest vor der Entscheidung eine Zeile pro Skill und gleicht deine Worte ab, nicht deine Absichten.

Ein Skill lohnt sich für eine Aufgabe, die du mit festem Ergebnis wiederholst: wöchentliche Notes, eine Pull-Request-Beschreibung, eine Release-Checkliste. Für eine einmalige Frage lohnt er sich nicht, und er ist nicht das Werkzeug für eine Regel, die immer gelten muss; das ist die Aufgabe eines Hooks. Auch ein Haufen ungenutzter Skills kostet dich, denn bei zu vielen beginnt Claude Code, Beschreibungen zu kürzen, die am wenigsten genutzten zuerst. Eine gute Beschreibung erhöht die Chancen, bringt einen Skill aber nicht dazu, bei einer Aufgabe zu feuern, für die er nie gedacht war, und eine Handvoll Läufe ist eine Demo, also ist deine Liste von Testanfragen die eigentliche Prüfung.

Die eine Regel: Schreib die Beschreibung in den Worten, die du tatsächlich tippst, wenn du um die Aufgabe bittest.