Ich leite ein Entwicklerteam, das seit gut einem Jahr fast ausschließlich mit Claude Code arbeitet. Nicht das "mal für einen Sprint ausprobiert" Level, sondern richtig tief drin: Unsere CI-Läufe laufen damit, unsere Pull-Request-Vorlagen sind faktisch Claude-Prompts. Irgendwann in diesem Prozess bin ich dann richtig ambitioniert geworden. Ich habe für unser Team eine eigene Sammlung von Skills gebaut: `code-review`, `debug-protocol` und `team-conventions`. Die leben in `.claude/skills/`, sehen wunderschön aus, haben all das YAML-Frontmatter, von dem man träumt – und in den ersten Wochen haben sie meistens einfach nur dagesessen. Still. Ignoriert. Wie ein Rauchmelder, der nur losheult, wenn schon was brennt.
Das Frustrierendste? Die Skill-Dateien waren korrekt. Die Pfade stimmten. Das Markdown war sauber und wunderschön dokumentiert. Der Skill hat einfach nie gefeuert. Und nach monatelangem Kopfkratzen habe ich endlich die Wahrheit erfahren: Es war nie die Schuld des Skills. Es war meine.
Die "Skill hat nicht gefeuert"-Falle
Für alle, die noch nicht im Abyss der Claude-Code-Skill-Konfiguration gestarrt haben, hier die Kurzfassung: Skills sind Ordner unter `.claude/skills/
```markdown
---
name: code-reivew
description: Use when the user asks for a code review.
---
```
Sieht harmlos aus. Aber die Art, wie Claude Code tatsächlich entscheidet, ob ein Skill feuert, ist diese: Er liest *jede* Skill-Beschreibung, mischt sie in seinen System-Prompt und vergleicht deine aktuelle Anfrage damit. Skill-Aktivierung ist im Grunde ein Intent-Matching-Spiel. Und wenn deine Beschreibung wie ein wörtlicher Keyword-Trigger geschrieben ist, ist das Spiel von Anfang an manipuliert.
Wir haben drei Wochen damit verbracht, Claude die Schuld zu geben, der API die Schuld zu geben, dem Mondstand die Schuld zu geben. Dann haben wir uns tatsächlich die offizielle Skill-Dokumentation unter [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) durchgelesen und erkannten etwas Unbequemes: Das Modell ist nicht faul, es ist nur wörtlich. Es kann nur einen Skill feuern, den es *als relevant erkennt* – anhand der Beschreibung. Und unsere Beschreibungen waren schrecklich.
Das eigentliche Problem: Beschreibungsmismatch
Das, was uns viel zu lange gebraucht hat zu verstehen: **Der Skill existiert nicht im Vakuum.** Er existiert in einem Suppe aus anderen Skills, eingebautem Verhalten und allem, was sonst noch in Claudes Kontext ist. Wenn ein Entwickler etwas tippt, führt Claude eine schnelle geistige Berechnung durch: *"Passt das zu einer Skill-Beschreibung? Wenn mehrere passen, welche ist am nächsten? Sollte ich nicht direkt antworten?"*
Wenn deine Skill-Beschreibung zu eng, zu vage oder zu keyword-fokussiert ist, wird Claude sie verfehlen. Und wenn deine Beschreibung mit einem anderen Skill oder einem eingebauten Befehl kollidiert, wird Claude die falsche wählen. Der Code in deiner SKILL.md ist nie das Problem. Die Metadaten sind es.
Hier sind die drei größten Fallstricke, in die reale Teams tappen.
Szenario 1: Der Code-Review-Skill, der immer schlief
Ich hatte unseren `code-review`-Skill mit der offensichtlichsten Beschreibung der Welt geschrieben: *"Verwenden, wenn der Benutzer eine Code-Review anfordert."* Einfach, oder? Falsch.
Unsere Entwickler sagten nie "code review". Sie sagten:
- "Kannst du meinen PR mal gegenchecken?"
- "Schau dir diesen Diff an, da stimmt irgendwas nicht."
- "Review das, bevor ich es shippe."
- "Ist das nicht over-engineered?"
Ratet mal, welcher Ausdruck den Skill ausgelöst hat? Keiner. Claude antwortete direkt, ohne jemals den Skill aufzurufen, weil die Phrase "code review" nie in der Nachricht vorkam. Die Lösung war peinlich einfach. Wir haben die Beschreibung umgeschrieben – semantisch statt wörtlich:
```yaml
description: >-
Verwenden für die Überprüfung von Code-Änderungen, Pull Requests, Diffs oder Merge Requests.
Auslöser sind Phrasen wie "Review diesen PR", "Check meinen Diff", "Gib dem Code einen Reality-Check",
"Ist das bereit zum Mergen" oder "Schau dir diese Änderungen an".
Nicht für allgemeines Debugging oder Code-Erklärungen.
```
Wir haben auch einen "Nicht für"-Klausel hinzugefügt. Diese einzige Änderung ließ den Skill etwa 80% häufiger feuern. Claude-Code-Skills sind im Kern Prompt-Engineering – und der Prompt ist die Beschreibung.
Szenario 2: Das Debugging-Protokoll, das uns ignorierte
Unser `debug-protocol`-Skill sollte der Held des Teams sein. Ein strukturierter, schrittweiser Prozess zum Reproduzieren von Bugs, Überprüfen von Logs, Inspezieren von Zuständen und Vorschlagen von Fixes. Er war wunderschön. Und hat auch nie gefeuert.
Warum? Weil die Beschreibung mit dem Wort "debug" begann. Und "debug" ist überall in Claude Code. Es gibt eine eingebaute Debug-Flagge, es gibt system-level Debugging-Verhalten, und es gibt wahrscheinlich drei weitere Skills im selben Verzeichnis mit ähnlicher Sprache. Wenn unsere Entwickler sagten "Hilf mir, diesen fehlgeschlagenen Test zu debuggen", hatte Claude vier plausible Kandidaten und wählte den mit der stärksten *generellen* Prompt-Relevanz – meistens das eingebaute Verhalten, nicht unseren Custom-Skill.
Wir haben zwei Lehren daraus gezogen:
1. **Gib Skills einzigartige, spezifische Namen.** `debug-protocol` ist generisch. `sentry-repro-protocol` oder `memory-leak-hunt` wären besser gewesen. Generische Namen werden von generischem Intent überdeckt.
2. **Nutze den manuellen Override.** In Claude Code kannst du immer `/debug-protocol` tippen, um einen Skill zu erzwingen. Das haben wir in unsere Teamkonventionen aufgenommen, und plötzlich war der Skill nicht tot – er brauchte nur eine direkte Einladung.
Aber hier die tiefere Erkenntnis: Das Modell hat den falschen Skill gewählt, weil *wir* eine Kollision entworfen haben. Wenn du zwei Skills hast, die ähnlich klingen, wird Claude raten. Lass die Beschreibungen sich gegenseitig ausschließen. Sage Claude explizit: "Verwende dies statt des allgemeinen Debugging-Verhaltens, wenn es sich um Server-Logs handelt."
Szenario 3: Der Team-Conventions-Skill, der alles vergaß
Das seltsamste Versagen kam von unserem `team-conventions`-Skill. Er enthielt die Regeln für Commit-Messages, Branch-Namensgebung und PR-Beschreibungen. Am Anfang einer Session funktionierte er wunderschön und hörte irgendwann um Nachricht 20 auf. Wir nahmen an, das Modell "vergisst" etwas. Es war kein Memory-Bug – es war Kontext.
Claude Code kippt alle Skill-Beschreibungen in den System-Prompt. Lange Beschreibungen fressen Kontext. Und wenn sich der Dialog aufbaut, fängt das System an, den System-Prompt zu komprimieren oder zu kürzen, um Platz zu machen. Unsere `team-conventions`-Beschriftung war ein Textwall – drei Absätze Firmen-Jargon. Das war das Erste, was über Bord ging, wenn der Kontextfenster knapp wurde.
Die Lösung war, die Beschreibung auf zwei bis drei Sätze zu schlankern und die eigentlichen Regeln in eine referenzierte Datei innerhalb des Skill-Ordners zu verschieben. Jetzt ist die Beschreibung nur noch ein Wegweiser: *"Verwenden für Commit-Messages, Branch-Namensgebung und PR-Konventionen. Vollständige Regeln in convention.md."* Das Modell kann das speichern, und wenn der Skill feuert, liest es die vollständige Datei. Wir haben auch nicht-Skill-Regeln in unsere `CLAUDE.md` Projekt-Memory-Datei verschoben, die für teamweite Anweisungen zuverlässiger geladen wird.
Praktische Lösungen, die du sofort umsetzen kannst
Nach Wochen des Schmerzes hier die Checkliste, die ich mir am ersten Tag gewünscht hätte.
Behandle die Beschreibung wie eine Suchanfrage
Wenn jemand deine Skill-Beschreibung suchen würde, würde sie dann mit der Sache übereinstimmen, die du eigentlich willst? Schreibe die Beschreibung wie einen semantischen Suchstring. Füge Synonyme, echte Phrasen, die dein Team benutzt, und explizite Ausschlüsse hinzu. Nimm nicht an, das Modell "wüsste, was du meinst". Es weiß nur, was du geschrieben hast.
Halte Skill-Dateien schlank
Eine Skill-Datei mit 500 Zeilen ist eine Last. Sie frisst Kontext, wird gekürzt und wird unzuverlässig. Halte die SKILL.md fokussiert auf die *Entscheidung*, wann sie feuert. Schiebe die schweren Details in Hilfsdateien – `prompt.md`, `criteria.md`, `checklist.md` – die Claude erst nach der Skill-Aktivierung liest.
Füge negative Beispiele hinzu
Das klingt kontraintuitiv, funktioniert aber. Erkläre in der Beschreibung explizit, wofür der Skill *nicht* ist. Schreibe: *"Nicht für allgemeine Architekturdiskussionen. Nicht für Syntaxfragen."* Das reduziert Falschtreffer und hilft dem Modell auch, ähnliche Skills voneinander zu unterscheiden. Negative Beispiele sind das schärfste Werkzeug in der Kiste.
Nutze `/` für manuellen Override
Egal wie gut deine Metadaten werden, es wird einen Moment geben, in dem die automatische Erkennung versagt. Bringe dein Team bei, `/skill-name` zu tippen, wenn sie die Aktivierung erzwingen müssen. Das ist kein Scheitern – es ist ein Fallback. Die klügsten Teams behandeln automatisches Skill-Feuern als Bequemlichkeit, nicht als Abhängigkeit.
Debugge es wie jeden anderen Code
Claude Code hat eine `--debug`-Flagge. Nutze sie. Überprüfe den System-Prompt, der am Anfang einer Session zusammengebaut wird, und bestätige, dass deine Skill-Beschreibungen tatsächlich darin stehen. Das klingt offensichtlich, aber wir haben herausgefunden, dass ein nachgestelltes Komma in einem unserer YAML-Frontmatter-Blöcke die gesamte Datei still und leise ungültig machte. Der Skill wurde nie geladen. Nicht wegen Intent-Matching – wegen eines Parse-Fehlers. Die Debug-Ausgabe hat es in zehn Sekunden aufgedeckt.
Teste mit verschiedenen Formulierungen
Teste nicht nur die exakte Phrase aus deiner Dokumentation. Öffne eine neue Session und tippe die unordentliche, menschliche, mehrdeutige Art, wie dein Team tatsächlich redet. "Wird dieser PR die Bombe sein?" sollte deinen Review-Skill auslösen, wenn deine Beschreibungen stimmen. Wenn nicht, ist deine Beschreibung noch nicht gut genug.
FAQ
Warum funktioniert mein Skill in einer neuen Session, hör aber später auf zu feuern?
Das ist fast immer Kontext-Kürzung. Lange Skill-Beschreibungen werden aus dem System-Prompt geworfen, wenn der Dialog wächst. Schlankere die Beschreibung, oder strukturiere mit einer Referenzdatei um. Es ist kein Memory-Problem – es ist ein Platzproblem.
Ist es besser, Keywords oder natürliche Sprache in Skill-Beschreibungen zu verwenden?
Beides, im richtigen Verhältnis. Beginne mit einem ein-Satz semantischen Beschreibung der *Absicht* ("verwenden für die Überprüfung von Code-Änderungen"), und füge dann eine Liste gängiger Trigger-Phrasen hinzu. Verlasse dich nicht nur auf Keywords, aber sei auch nicht so abstrakt, dass nichts passt.
Kann ein Custom-Skill das eingebaute Claude-Code-Verhalten überschreiben?
Nicht direkt. Eingebautes Verhalten ist auf einer Ebene verdrahtet, die dein Skill nicht überschreiben kann. Aber du kannst den Wettbewerb gewinnen, indem du deine Skill-Beschreibung spezifischer und relevanter für die tatsächliche Situation deines Teams machst. Wenn du feststeckst, nutze `/skill-name`, um es zu erzwingen, oder formuliere die Anfrage um, sodass der eingebaute Pfad nicht mehr passt.
Wie weiß ich, ob meine Skill-Datei überhaupt geladen wird?
Führe `claude --debug` aus und überprüfe die Ausgabe. Du solltest deine Skills in der System-Prompt-Zusammenstellung aufgelistet sehen. Wenn dein Skill nicht aufgeführt ist, überprüfe das YAML-Frontmatter, die Ordnerstruktur und den Dateinamen. Ein Skill-Ordner ohne gültige `SKILL.md` ist nur Dekoration.
Die Quintessenz
Hier ist die unbequeme Wahrheit: Wenn ein Skill nicht feuert, ist die Skill-Datei fast nie das Problem. Das Problem ist, wie gut du die menschliche Absicht – "Überprüfe meine Arbeit, befolge unsere Regeln, behebe diesen Bug auf die Art, die wir vereinbart haben" – in die Metadaten übersetzt hast, die Claude tatsächlich liest. Es geht nicht darum, besseren Code zu schreiben. Es geht darum, bessere *Wegweiser* zu schreiben.
Wenn du frustriert von stillen Skills bist, schreibe nicht deine Markdown von Grund auf neu. Schreibe deine Beschreibungen um. Füge echte Beispiele hinzu. Füge Ausschlüsse hinzu. Halte die Datei schlank. Und wenn alles andere scheitert, tippe einfach `/skill-name` direkt und mach mit deinem Tag weiter.
Der Skill ist nicht kaputt. Und glaub es oder nicht, auch Claude nicht. Wir haben nur vergessen, dass das Modell mehr als ein vager Nicken über den Raum braucht, um zur Party eingeladen zu werden.
Comments (0)
No comments yet. Be the first to comment!
Leave a Comment