Skill triggert nicht, was Du in 10 Schritten pruefst bevor Du wieder /befehl tippst

Du hast eine Skill geschrieben, sie liegt unter ~/.claude/skills/<name>/SKILL.md, und Claude tut so als gaebe es sie nicht. Du sagst "schau Dir das Code-Review mal an" und kriegst eine generische Antwort statt der Skill-Logik die Du hingelegt hast. Das ist nicht selten. Skills sind ein probabilistischer Mechanismus, kein deterministischer. Claude entscheidet pro Prompt ob die Trigger-Beschreibung matcht, und das geht oefter schief als man denkt. Hier ist der Debugging-Pfad den ich gehe wenn eine Skill nicht läuft.

1. SKILL.md liegt am richtigen Ort

Erste Pruefung. Eine Skill braucht genau diese Struktur, ~/.claude/skills/<skillname>/SKILL.md. Das Verzeichnis kann tiefer geschachtelt sein mit Helper-Files oder Bundle-Scripts, aber das SKILL.md muss direkt im Skill-Root liegen. Falls Du es als skill.md (klein) oder README.md benannt hast, triggert nichts. Claude scannt nur SKILL.md mit grossem S.

Test: ls ~/.claude/skills/*/SKILL.md. Wenn Dein Skill nicht in der Liste steht, ist das schon das Problem.

2. Frontmatter ist gueltiges YAML

Skills laden über die Frontmatter. Wenn das YAML kaputt ist, ueberspringt Claude die Skill ohne Warnung. Typische Killer: Anfuehrungszeichen die nicht schließen, Tabs statt Spaces, Kommentare mit # mitten in einem Multi-Line-Value, falsche Einrückung bei allowed-tools.

Schnell-Check: yq eval ~/.claude/skills/<name>/SKILL.md oder einfach in einem YAML-Linter pasten. Wenn das durchgeht, ist die Frontmatter syntaktisch OK. Falls Du yq nicht hast, oeffne die Datei in einem Editor mit YAML-Highlighting und schau ob die Farben stimmen.

3. Die description ist kein Doku-Text, sie ist der Trigger

Hier liegt der Hauptfehler aus dem 90 Prozent meiner Skill-Probleme kamen. Die description in der Frontmatter ist nicht Beschreibung für Menschen, sie ist der Trigger den Claude liest um zu entscheiden ob die Skill passt. Wenn da steht "Hilft bei Code-Themen", triggert das nie sauber weil "Code-Themen" zu allgemein ist.

Konkret schreiben. Statt "für Code-Review" lieber "use this skill when the user asks to review, audit, or critique TypeScript or JavaScript code for bugs, security issues, or performance problems". Das ist eine Trigger-Beschreibung, kein Marketing-Text. Anthropic dokumentiert das auf der Skills-Page explizit unter Troubleshooting, und in der Praxis ist das der mit Abstand wichtigste Hebel.

4. Description-Length prüfen

Skills haben eine Description-Length-Limitierung. Wenn Du in der Frontmatter eine 800-Zeichen-Erklärung schreibst, wird die irgendwann abgeschnitten und der Trigger-Teil rutscht raus. Anthropic listet das in der Troubleshooting-Sektion als "Skill descriptions are cut short".

Faustregel die bei mir funktioniert: zwei Sätze, der erste sagt was die Skill macht, der zweite sagt wann sie triggern soll. Wenn Du mehr Kontext geben willst, gehört der in den Skill-Body, nicht in die Frontmatter.

5. Den allowed-tools-Block prüfen

Wenn Deine Skill allowed-tools setzt und ein Tool dabei ist das im aktuellen Setup nicht existiert, kann Claude die Skill verweigern. Typischer Fall, Du hast in der Skill Bash und Edit allowed, aber in der Session läuft Plan-Mode der Edit blockt. Dann triggert die Skill nicht oder triggert ohne dass sie ihre Arbeit tun kann.

Quick-Fix wenn Du Dir nicht sicher bist, kommentiere allowed-tools voruebergehend aus. Wenn die Skill dann triggert, weißt Du dass das Permission-Problem war. Danach wieder rein mit den richtigen Tools.

6. Plan-Mode + Skills, was zusammen passiert

Skills triggern grundsaetzlich auch im Plan-Mode, aber sie können nichts schreiben oder ausführen. Wenn Deine Skill auf Edit oder Bash angewiesen ist, sieht es so aus als wuerde sie nicht laufen. Sie läuft, aber Claude antwortet im Plan-Layer statt zu handeln.

Test, schalte Plan-Mode mit Shift+Tab aus und schick den gleichen Prompt nochmal. Wenn die Skill jetzt feuert, hattest Du nur ein Plan-Mode-Artefakt. Notiere Dir das, weil das beim nächsten Mal genauso aussehen wird wie ein kaputter Trigger.

7. Skill-Prompt explizit testen

Wenn Du nicht sicher bist warum die Skill nicht triggert, sag es Claude direkt. "Es gibt eine Skill <name> unter ~/.claude/skills/, schau in die SKILL.md und nutz sie für folgenden Task." Damit umgehst Du den probabilistischen Trigger-Mechanismus und Claude lädt die Skill manuell.

Wenn das funktioniert, ist die Skill technisch in Ordnung und Dein Problem ist nur die Trigger-Beschreibung. Wenn das auch nicht funktioniert, ist die Skill selbst kaputt oder am falschen Ort.

8. settings.json schaut ob Skills enabled sind

In ~/.claude/settings.json kann es einen Block geben der Skills selektiv enabled oder disabled. Wenn Du irgendwann mal mit skills.disabled rumgespielt hast oder ein Plugin das gesetzt hat, kann Deine Skill global ausgeschaltet sein.

cat ~/.claude/settings.json | grep -i skill. Falls da was steht das Deine Skill ausschliesst, raus damit. Globale Settings sind hier ueblicher als projekt-lokale, also wenn Du mehrere Claude-Setups hast schau ueberall.

9. Konflikt mit anderen Skills

Wenn Du drei Skills hast mit ähnlichen Trigger-Beschreibungen, kann es passieren dass Claude die falsche wählt. Beispiel, code-review und security-audit ueberlappen oft, weil Code-Review fast immer Security-Aspekte hat. Claude triggert dann mal die eine, mal die andere, und Du denkst die eigene Skill ist kaputt.

Test, deaktiviere die anderen Skills temporaer (umbenennen von SKILL.md zu SKILL.md.bak) und schick den Prompt nochmal. Wenn Deine Skill jetzt zuverlaessig triggert, hast Du Trigger-Konflikt. Lösung ist die Trigger-Beschreibungen schaerfer abzugrenzen oder die Skills zu mergen.

10. Bundle-Script feuert nicht, ist nicht das gleiche wie Skill triggert nicht

Letzte Falle. Eine Skill kann triggern und trotzdem nichts sichtbares machen, weil ihr Bundle-Script kaputt ist. Claude lädt den Body, ruft das Script, das Script crasht still, Claude antwortet mit dem was er aus dem Body gelernt hat. Sieht aus wie "Skill triggert nicht" ist aber "Skill triggert, Script crasht".

Test, im Skill-Verzeichnis das Script manuell aufrufen mit den gleichen Argumenten die Claude rufen wuerde. Wenn das per Hand crasht, weißt Du wo Du suchen musst. Stderr-Output von Skill-Scripts wird bei Claude Code normalerweise verschluckt, also musst Du das ausserhalb der Session testen.

Was als nächstes

Wenn die Skill jetzt triggert, schreib in Dein eigenes Memory oder ein internes CHANGELOG was der eigentliche Fehler war. Die meisten Skill-Trigger-Probleme wiederholen sich, und beim dritten Mal willst Du nicht wieder durch alle 10 Schritte. Pattern speichern, schneller debuggen.

Wenn Du tiefer in Skill-Komposition rein willst, schau Dir das Playbook erste-eigene-skill-in-30-min (/playbooks/erste-eigene-skill-in-30-min) an, da geht es um Bundle-Scripts und allowed-tools im Detail. Für den nächsten Schritt nach Skills (wann ist Sub-Agent besser, wann MCP-Tool) lohnt sich der Vergleich in der Lesson L4-04 (/levels/4/hooks-und-skills).

Source

• Skills Doku, Troubleshooting-Sektion: https://code.claude.com/docs/en/skills
• Frontmatter-Spec und Skill-Aktivierung dort verifiziert am 2026-05-23