Claude Skill triggert nicht? 6 Checks zum Fix

Du hast einen Skill installiert, Claude um genau die Sache gebeten, für die der Skill da ist — und Claude hat weitergemacht, als gäbe es den Skill nicht. Kein Fehler, keine Warnung, nichts zum Greppen. Nur Stille.

Wir sehen das ständig. SkillProof installiert und testet jeden Skill in unserem Katalog auf einer sauberen Maschine, und ausbleibendes Triggern ist der häufigste Defekt, den wir finden. Er ist auch der am besten reparierbare: Fast jede „Skill funktioniert nicht"-Meldung in unseren Testprotokollen geht auf eine von sechs Ursachen zurück, und fünf davon lassen sich in unter einer Minute ausschließen.

Geh zuerst die Checkliste durch. Der Rest des Artikels vertieft jeden Check mit Symptom, Ursache und Fix.

Die 30-Sekunden-Checkliste

1. Richtiger Ordner? Die Datei muss unter ~/.claude/skills/<skill-name>/SKILL.md liegen — ein Ordner pro Skill, Dateiname exakt SKILL.md.
2. Neu gestartet? Claude scannt Skills beim Session-Start. Änderungen mitten in der Session bleiben unsichtbar, bis du neu startest.
3. Namenskollision? Zwei Skills mit demselben name verdecken sich gegenseitig. Nur einer überlebt.
4. Description zu vage? Wenn die Description nicht erwähnt, wonach Nutzer wörtlich fragen, matcht Claude sie nie. Das ist Ursache Nummer eins.
5. Frontmatter valide? Ein einziges kaputtes YAML-Zeichen macht den gesamten Skill unsichtbar — lautlos.
6. Konkurrierender Skill? Ein anderer installierter Skill mit überlappender Description gewinnt womöglich den Match.

Bestehen alle sechs Checks und der Skill aktiviert sich, aber der Output ändert sich nicht, ist das ein anderes Versagen. Spring zu wenn er triggert, aber nichts tut.

Check 1: Der Skill liegt im falschen Ordner

Symptom. Der Skill taucht nie auf, wenn du Claude fragst: „Welche Skills hast du installiert?" Als hättest du ihn nie kopiert.

Ursache. Claude schaut nur an bestimmten Orten nach: ~/.claude/skills/ für persönliche Skills und .claude/skills/ innerhalb eines Projekts für Projekt-Skills. Darin ist das Layout strikt: ein Ordner pro Skill, mit einer Datei namens exakt SKILL.md. Die Fehler, die wir beim Installieren von Community-Skills fürs Testen am häufigsten sehen: das ganze geklonte Repo kopieren (der Pfad wird dann skills/some-repo/skills/pdf-helper/SKILL.md, eine Ebene zu tief), SKILL.md ohne eigenen Ordner direkt in ~/.claude/skills/ ablegen — und kleingeschriebenes skill.md, das manche Dateisysteme verzeihen und andere nicht.

Fix. Prüf es im Terminal:

ls ~/.claude/skills/*/SKILL.md

Jeder erwartete Skill sollte genau eine Zeile ausgeben. Fehlt ein Skill oder hat sein Pfad zu viel Verschachtelung, verschieb den Ordner so, dass die SKILL.md eine Ebene unter skills/ sitzt. Unser Installations-Guide zeigt das korrekte Layout für jede Plattform.

Check 2: Du hast nicht neu gestartet

Symptom. Die Ordnerstruktur stimmt, du hast sie vor zwei Minuten repariert — und Claude sieht den Skill in derselben Unterhaltung immer noch nicht.

Ursache. Die Skill-Erkennung passiert einmal, beim Start. Claude liest das Frontmatter jeder auffindbaren SKILL.md und hält diesen Index für die Session. Ein Skill, den du mitten in der Session hinzufügst, umbenennst oder editierst, existiert für die laufende Session nicht.

Fix. In Claude Code: Session beenden und neue starten. In der Desktop-App: komplett beenden mit Cmd+Q auf macOS (das Fenster zu schließen zählt nicht) und neu öffnen. Dieser Check ist so billig auszuschließen, dass wir ihn vor jedem tieferen Debugging machen — so wie man den Router neu startet, bevor man beim Provider anruft.

Check 3: Eine Namenskollision verdeckt deinen Skill

Symptom. Du hast den Skill installiert, der Ordner stimmt, du hast neu gestartet — und die Skill-Liste zeigt entweder nichts Neues oder einen anderen Skill, der auf denselben Namen hört.

Ursache. Skill-Namen müssen eindeutig sein. Teilen sich ein persönlicher und ein Projekt-Skill einen name, oder liefern zwei installierte Packs beide einen Skill namens seo-audit mit, verdeckt einer den anderen ohne Warnung. Wir sind bei unserer eigenen Katalogarbeit hineingelaufen: Zwei nebeneinander installierte Marketing-Packs erzeugten ein stilles Duplikat, und der Skill, den wir wollten, lud nie.

Fix. Such nach Duplikaten:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Jede Ausgabe bedeutet eine Kollision. Benenne den Ordner und das name-Feld der Kopie um, die du kontrollierst, starte neu und prüf die Liste erneut.

Check 4: Die Description sagt nie, wann gefeuert werden soll

Symptom. Der Skill taucht in der Liste der installierten Skills auf. Rufst du ihn beim Namen, funktioniert er einwandfrei. Bittest du in eigenen Worten um die Aufgabe, passiert nichts.

Ursache. Das ist der große Punkt, und er verdient seine eigene Sektion — hier die Kurzfassung: Claude entscheidet über das Laden eines Skills, indem es nur dessen description-Feld liest und mit deiner Anfrage vergleicht. Sagt die Description, was der Skill ist, statt wann er zu benutzen ist, kommt der Match nie zustande. Der Skill ist nicht kaputt. Er ist unbeworben.

Fix. Schreib die Description rund um die Formulierungen neu, die Nutzer tatsächlich tippen. Der Deep Dive unten zeigt drei echte Fehlermuster und ihre Rewrites.

Check 5: Das Frontmatter ist ungültig

Symptom. Ordner korrekt, Neustart erledigt, keine Namenskollision — und der Skill taucht trotzdem gar nicht in der Liste auf. Sieht aus wie Check 1, aber der Pfad stimmt.

Ursache. Der YAML-Block oben in der SKILL.md ließ sich nicht parsen, und ein Skill mit unparsbarem Frontmatter wird schlicht übersprungen. Die üblichen Verdächtigen aus unseren Testnotizen: ein fehlendes schließendes ---, ein unmaskierter Doppelpunkt in der Description („Use for: reports" bricht den Parser), typografische Anführungszeichen aus einem Blogpost oder Google Doc, Tabs zur Einrückung — und ein name, der die Formatregeln verletzt (nur Kleinbuchstaben, Ziffern und Bindestriche, maximal 64 Zeichen; Descriptions enden bei 1024).

Fix. Öffne die Datei und prüf den Block mit bloßem Auge — oder spar dir das: Füg ihn in unseren Skill-Validator ein, und er meldet Parse-Fehler, Formatverstöße und Smart-Quote-Kontamination sofort. Parst das Frontmatter und der Skill versteckt sich trotzdem, geh zurück zu Check 1, denn dann ist es fast immer der Pfad.

Check 6: Ein anderer Skill gewinnt den Match

Symptom. Du bittest um die Aufgabe, und ein Skill aktiviert sich tatsächlich — nur nicht deiner. Oder das Verhalten ändert sich auf eine Weise, die zu den Anweisungen eines anderen Skills passt.

Ursache. Wenn mehrere Descriptions eine Anfrage plausibel abdecken, wählt Claude die, die sich wie der beste Treffer liest — und eine breitere, selbstbewusstere Description schlägt tendenziell eine engere. Installier einen allgemeinen „Writing Assistant"-Skill neben deinem „Release Notes Formatter", und der Generalist kann jede Schreibanfrage schlucken, Release Notes eingeschlossen.

Fix. Schärfe beide Descriptions, damit sich ihre Territorien nicht überlappen, und ergänze explizite Ausschlüsse. Eine Zeile wie „Do NOT use for release notes or changelogs" in der Description des Generalisten ist grob — und funktioniert. Kontrollierst du den störenden Skill nicht, deaktivier ihn, während du deinen testest, und entscheide dann, ob du wirklich beide brauchst.

Warum Descriptions scheitern: der Deep Dive

Wir testen jeden Skill, den wir listen, und Trigger-Probleme sind der Hauptgrund, warum Skills in unseren Reviews schlecht abschneiden. Nicht kaputte Skripte, nicht schlechte Anweisungen. Descriptions, die nie gematcht werden.

Die Mechanik erklärt, warum. Beim Start lädt Claude von jedem Skill nur name und description, grob hundert Tokens. Der Body — wie brillant auch immer — bleibt auf der Platte, bis die Description den Match gegen deine Anfrage gewinnt. Die Description ist ein Verkaufspitch an ein Modell, und die meisten Autoren schreiben sie wie ein Museumsschild.

Hier die drei Muster, die wir am häufigsten abwerten — mit den Rewrites, die sie in unseren Nachtests repariert haben.

Muster 1: das bescheidene Etikett.

description: Helps with documents.

Nichts hier verbindet sich mit irgendetwas, das ein Nutzer tippen würde. Vergleich das mit Anthropics DOCX-Skill, der unsere Trigger-Tests im ersten Lauf bestand. Seine Description nennt das Dateiformat, die Aktionen und die Formulierungen, die ihn aktivieren sollen. Der Rewrite nach derselben Logik:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Muster 2: der interne Name.

description: Runs the acme-formatter pipeline with corporate config.

Das beschreibt die Implementierung. Kein Nutzer bittet Claude, „die acme-formatter-Pipeline laufen zu lassen"; er bittet darum, „diesen Bericht aufzuräumen, bevor ich ihn an einen Kunden schicke". Der Rewrite übersetzt den Skill ins Vokabular des Nutzers:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Muster 3: die gierige Decke.

description: Use for any writing task.

Das gegenteilige Versagen. Das matcht alles — und kollidiert damit mit jedem anderen schreibnahen Skill, feuert, wenn es nicht sollte, und Nutzer deaktivieren es innerhalb einer Woche. Der Rewrite verengt den Anspruch und zäunt die Ränder ein:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

Der Test, den wir beim Review anlegen: nur die Description lesen und fragen: „Wenn ein Nutzer seine Anfrage natürlich tippen würde — würden diese Wörter sie matchen?" Schreib in der dritten Person, sag, was der Skill tut und wann er greift, und nimm die Substantive auf, die Leute wirklich benutzen. Wenn du einen Skill von Grund auf schreibst, behandelt unser Authoring-Guide das ausführlicher, und Anthropics Skill Creator erzeugt standardmäßig Descriptions, die diesen Test bestehen.

Triggern richtig testen

Die meisten testen einen Skill, indem sie ihn beim Namen nennen: „Benutz den Invoice-Skill dafür." Das beweist nichts, denn das Nennen eines Skills umgeht den Description-Match komplett. Das ist, wie einen Rauchmelder per Testknopf zu prüfen und daraus zu schließen, das Haus sei feuerfest.

Teste so, wie ein Nutzer fragen würde — jedes Mal in einer frischen Session. Für einen Rechnungs-Extraktions-Skill drei Formulierungen, die feuern sollten:

• „Zieh die Summen aus diesen Rechnungs-PDFs."
• „Ich hab 30 Lieferantenrechnungen, bring Beträge und Daten in eine Tabelle."
• „Extrahier die Einzelposten aus dieser Rechnung."

Und zwei, die nicht feuern sollten:

• „Fass mir dieses PDF zusammen." (Generische PDF-Arbeit; das Revier eines anderen Skills.)
• „Schreib diesem Kunden eine Rechnungs-E-Mail." (Verfassen, nicht extrahieren.)

Wenn eine Soll-feuern-Formulierung nichts auslöst, frag Claude direkt: „Welchen deiner installierten Skills würdest du für diese Anfrage benutzen, und warum?" Die Antwort zeigt dir die Match-Logik und deutet meist direkt auf die Schwachstelle in der Description. Aktivieren die Soll-nicht-feuern-Formulierungen den Skill trotzdem, hast du eine gierige Decke und brauchst Ausschlüsse. Das ist exakt das Protokoll, das wir im Katalog-Testing fahren — und dieselbe Disziplin, die der Systematic Debugging-Skill lehrt: erst reproduzieren, eine Variable nach der anderen, den Belegen glauben.

Wenn er triggert, aber nichts tut

Angenommen, der Skill aktiviert sich tatsächlich. Das kannst du bestätigen, indem du Claude mitten in der Unterhaltung fragst, ob für die Anfrage ein Skill geladen wurde — es wird es dir sagen. Aber der Output sieht genauso aus wie vor der Installation.

Das ist kein Trigger-Problem, und nichts von oben wird es beheben. Es ist ein Body-Problem: Die Anweisungen im Skill sind zu vage, um Verhalten zu ändern, oder der Skill referenziert mitgelieferte Dateien, die an den erwarteten Pfaden nicht existieren, oder er ruft ein Skript auf, dessen Abhängigkeiten nie deklariert wurden. Die Description hat den Skill durch die Tür gebracht, und drinnen ist der Inhalt umgekippt.

In unseren Tests ist das der andere große Eimer an Fehlschlägen, ungefähr das Spiegelbild der Trigger-Defekte — und der Hauptgrund, warum rund die Hälfte der Community-Skills unsere Tests nicht besteht. Der schnelle Diskriminator: Hat sich das Verhalten gar nicht geändert, verdächtige das Triggern; hat es sich geändert, aber schlecht oder teilweise, verdächtige den Body. Debugge entsprechend, denn die Fixes überschneiden sich nicht.

Plattform-Fallstricke

Das Skill-Format ist überall identisch, die Erkennung aber nicht — und ein Skill, der an einem Ort funktioniert, kann anderswo tot wirken.

Claude Code liest Ordner auf der Platte: ~/.claude/skills/ persönlich, .claude/skills/ pro Projekt. Beide laden; Namenskollisionen zwischen den beiden Ebenen lösen sich zu einem Gewinner auf (Check 3). Nach jeder Änderung die Session neu starten.

Claude Desktop liest deine Skill-Ordner nicht. Skills werden als Zip über die Einstellungen unter Capabilities hochgeladen, und das Zip muss den Skill-Ordner auf oberster Ebene enthalten — nicht die nackte SKILL.md und kein Wrapper-Verzeichnis. Ein Skill, der in Claude Code sauber triggert, ist auf Desktop schlicht abwesend, bis du ihn dort separat hochlädst.

claude.ai nimmt denselben Upload-Weg wie Desktop, mit zwei zusätzlichen Verliermöglichkeiten: Skills brauchen die aktivierte Code-Ausführung auf deinem Plan, und Workspace-Admins können Skills organisationsweit deaktivieren — dann wird nichts, was du hochlädst, je feuern, und keine Fehlermeldung wird es dir sagen. Frag deinen Admin, bevor du einen Abend mit Description-Rewrites verbrennst.

Noch eine plattformübergreifende Falle: Ein für Claude Code geschriebener Skill-Body, der git aufruft oder lokale Projektdateien liest, triggert auf claude.ai korrekt — und scheitert dann in der Sandbox. Das ist ein Body-Problem im Plattform-Kostüm.

Wann du aufhören solltest zu debuggen

Ist es dein eigener Skill, mach weiter — jeder Fix oben ist dauerhaft, und der Validator plus der Fünf-Formulierungen-Test bringen dich ans Ziel. Ist es ein Drittanbieter-Skill und du hast mehr als zwanzig Minuten am Description-Feld eines anderen verbrannt, ist es fair, ihn gegen einen zu tauschen, der diese Checkliste schon hinter sich hat: Jeder Skill auf unseren Bestenlisten hat das Trigger-Testing auf einer sauberen Maschine bestanden, bevor wir ihn gelistet haben.

FAQ

Wie bestätige ich, dass ein Skill überhaupt installiert ist?

Frag Claude in einer frischen Session: „Welche Skills hast du installiert?" Fehlt dein Skill in der Antwort, liegt das Problem bei der Erkennung (Checks 1, 3 und 5: Ordner, Kollision, Frontmatter), nicht beim Triggern. Wird er gelistet, aktiviert sich aber nie, liegt das Problem bei der Description (Checks 4 und 6).

Kann ich den Skill nicht einfach erzwingen, indem ich ihn beim Namen nenne?

Ja. „Benutz den docx-Skill, um dieses Memo zu schreiben" lädt den Skill direkt, und als Workaround beim Debuggen ist das völlig in Ordnung. Ein Fix ist es aber nicht: Ein Skill, den du jedes Mal beim Namen herbeirufen musst, ist ein Skill mit kaputter Description — und du wirst das Herbeirufen genau dann vergessen, wenn es darauf ankommt.

Warum funktioniert mein Skill in Claude Code, aber nicht auf Desktop oder claude.ai?

Unterschiedliche Erkennungswege. Claude Code liest Ordner auf der Platte; Desktop und claude.ai sehen nur Skills, die über die Einstellungen als Zip mit dem Skill-Ordner auf oberster Ebene hochgeladen wurden. Auf claude.ai zusätzlich prüfen: Code-Ausführung aktiviert, und der Workspace-Admin hat Skills nicht komplett abgeschaltet.

Macht das Installieren zu vieler Skills das Triggern kaputt?

Nicht direkt. Fünfzig Skills kosten ein paar tausend Tokens Metadaten, das ist billig. Das echte Risiko ist Überlappung: Je mehr Descriptions du installierst, desto wahrscheinlicher beanspruchen zwei dasselbe Territorium — und dann gewinnt manchmal die falsche (Check 6). Installier nach Bedarf und miste Skills aus, die nie feuern.

Mein Skill hat gestern getriggert und heute nicht. Ist das normal?

Gelegentlich, ja. Das Matching ist modellgetrieben, keine Regex — eine grenzwertige Description feuert also auf eine Formulierung und verfehlt eine fast identische. Wenn ein Skill wackelig statt tot ist, behandle es als schwache Description: Ergänze die exakten Formulierungen, die danebengegangen sind, im Description-Feld, starte neu und teste erneut. Zuverlässige Skills triggern auf jede vernünftige Formulierung — deshalb testen wir mit fünf, nicht mit einer.