Fehlerbehebung bei Skills

Fehlerbehebung bei Skills

Wichtige Erkenntnisse

• Beginne mit dem Skills-Validator-Tool – es erkennt strukturelle Probleme, bevor du Zeit mit der Fehlersuche an anderer Stelle verbringst
• Wenn ein Skill nicht ausgelöst wird, liegt die Ursache fast immer in der Beschreibung – füge Auslösephrasen hinzu, die dem entsprechen, wie du Anfragen tatsächlich formulierst
• Wenn ein Skill nicht geladen wird, prüfe, ob sich SKILL.md in einem benannten Verzeichnis befindet (nicht im Stammverzeichnis der Skills) und ob der Dateiname genau SKILL.md lautet
• Wenn der falsche Skill verwendet wird, sind deine Beschreibungen zu ähnlich – mache sie unterscheidbarer
• Prüfe bei Laufzeitfehlern Abhängigkeiten, Dateiberechtigungen (chmod +x) und Pfadtrenner (verwende überall Schrägstriche)

Wenn Skills nicht funktionieren, lässt sich das Problem meist einer von wenigen Kategorien zuordnen: Der Skill wird nicht ausgelöst, lädt nicht, hat Konflikte oder schlägt zur Laufzeit fehl. Die gute Nachricht ist, dass die meisten Lösungen recht unkompliziert sind.

Verwende den Skills-Validator

Das Erste, was du ausprobieren solltest, ist der Befehl claude plugin validate. Führe in deiner Shell claude plugin validate ~/.claude/skills für persönliche Skills oder claude plugin validate .claude/skills für Projekt-Skills aus. Dafür ist Claude Code v2.1.233 oder höher erforderlich.

Der Validator findet SKILL.md-Dateien, deren Frontmatter nicht geparst werden kann, sodass du dieses Problem erkennst, bevor du Zeit mit der Fehlersuche an anderer Stelle verbringst. Das Video oben zeigt einen separaten Verifier, den du mit uv installierst.

Skill wird nicht ausgelöst

Dein Skill existiert und besteht die Validierung, aber Claude verwendet ihn nicht, wenn du es erwartest. Die Ursache liegt fast immer in der Beschreibung.

Claude verwendet semantisches Matching, daher muss sich deine Anfrage inhaltlich mit der Beschreibung überschneiden. Wenn die Überschneidung nicht ausreicht, gibt es keine Übereinstimmung. So gehst du vor:

• Vergleiche deine Beschreibung damit, wie du Anfragen tatsächlich formulierst
• Füge Auslösephrasen hinzu, die Nutzer tatsächlich sagen würden
• Teste mit Variationen wie „hilf mir, das zu profilen", „warum ist das langsam?", „mach das schneller"
• Wenn eine Variation den Skill nicht auslöst, füge diese Schlüsselwörter zu deiner Beschreibung hinzu

Skill lädt nicht

Wenn dein Skill nicht erscheint, wenn du Claude fragst, „welche Skills verfügbar sind", prüfe diese strukturellen Anforderungen:

• Die Datei SKILL.md muss sich in einem benannten Verzeichnis befinden, nicht im Stammverzeichnis der Skills
• Der Dateiname muss genau SKILL.md lauten – „SKILL" in Großbuchstaben, „md" in Kleinbuchstaben

Führe claude --debug aus, um Ladefehler zu sehen. Achte auf Meldungen, die den Namen deines Skills erwähnen. Manchmal führt dich das allein direkt zum Problem.

Falscher Skill wird verwendet

Wenn Claude den falschen Skill verwendet oder zwischen Skills verwirrt zu sein scheint, sind deine Beschreibungen wahrscheinlich zu ähnlich. Mache sie unterscheidbar. So spezifisch wie möglich zu sein hilft Claude nicht nur dabei, zu entscheiden, wann dein Skill verwendet werden soll – es verhindert auch Konflikte mit anderen ähnlich klingenden Skills.

Prioritätskonflikte bei Skills

Wenn dein persönlicher Skill ignoriert wird, hat möglicherweise ein Enterprise- oder höher priorisierter Skill denselben Namen.



Wenn es beispielsweise einen Enterprise-Skill „code-review" gibt und du auch einen persönlichen Skill „code-review" hast, gewinnt immer der Enterprise-Skill. Deine Optionen:

1. Benenne deinen Skill in etwas Unterscheidbareres um (das ist meist der einfachere Weg)
2. Sprich mit deinem Admin über den Enterprise-Skill

Plugin-Skills erscheinen nicht

Du hast ein Plugin installiert, siehst aber seine Skills nicht? Führe /plugin aus und prüfe, ob das Plugin unter Installed aufgeführt und aktiviert ist, und lies dann den Tab Errors. Wenn du es während dieser Sitzung installiert hast, führe /reload-plugins aus.

Wenn Skills danach immer noch nicht erscheinen, ist möglicherweise die Plugin-Struktur falsch. Skills werden aus einem skills/-Verzeichnis im Plugin-Stammverzeichnis geladen, nicht aus .claude-plugin/. Führe in deiner Shell claude plugin validate für das Verzeichnis des Plugins aus, um dessen Manifest und das Frontmatter jedes Skills zu prüfen.

Laufzeitfehler

Der Skill lädt, schlägt aber während der Ausführung fehl. Ein paar häufige Ursachen:

• Fehlende Abhängigkeiten: Wenn dein Skill externe Pakete verwendet, müssen diese installiert sein. Füge Informationen zu Abhängigkeiten in deine Skill-Beschreibung ein, damit Claude weiß, was benötigt wird.
• Berechtigungsprobleme: Skripte benötigen Ausführungsberechtigung. Führe chmod +x für alle Skripte aus, auf die dein Skill verweist.
• Pfadtrenner: Verwende überall Schrägstriche, auch unter Windows.

Schnelle Checkliste zur Fehlerbehebung

• Wird nicht ausgelöst? Verbessere deine Beschreibung und füge Auslösephrasen hinzu.
• Lädt nicht? Prüfe deinen Pfad, Dateinamen und die YAML-Syntax.
• Falscher Skill verwendet? Mache die Beschreibungen unterscheidbarer voneinander.
• Wird überschattet? Prüfe die Prioritätshierarchie und benenne bei Bedarf um.
• Plugin-Skills fehlen? Prüfe /plugin auf Fehler und führe dann /reload-plugins aus.
• Laufzeitfehler? Prüfe Abhängigkeiten, Berechtigungen und Pfade.

Lektionsreflexion

• Bist du in deiner eigenen Arbeit schon auf eines dieser Fehlerbehebungsszenarien gestoßen? Welche Lösung hätte dir am meisten Zeit gespart?
• Wie würdest du einen Prozess einrichten, um Skills zu validieren, bevor du sie mit deinem Team teilst?

Kursabschluss

Herzlichen Glückwunsch zum Abschluss von Introduction to Agent Skills! Du hast gelernt, wie du Skills in Claude Code erstellst, konfigurierst, teilst und Fehler behebst. Wenn du anfängst, Skills für deine eigenen Workflows zu erstellen, denke daran, dass die besten Skills aus echten Problempunkten entstehen – beginne mit den Anweisungen, die du am häufigsten wiederholst.