Claude Skills und SKILL.md für Entwickler: VS Code, JetBrains, Cursor

Die meisten Teams missbrauchen Claude Skills auf eine von zwei Arten. Sie verwandeln entweder SKILL.md in eine Ablage für alles Mögliche oder sie scheitern nie, sich von riesigen kopierten Prompts zu verabschieden.

Beide Ansätze sind schlampig. Wenn Sie möchten, dass Skills in einem echten Entwickler-Workflow funktionieren, müssen Sie sie wie Code und operative Logik behandeln, nicht wie Prompt-Poesie.

Claude Skills sind Verzeichnisse, die durch SKILL.md verankert sind und optionale Skripte, Referenzen und Assets enthalten. Sie funktionieren aufgrund progressiver Offenlegung. Der Agent lädt zunächst nur kompakte Metadaten wie den Skill-Namen und die Beschreibung und liest die vollständigen Anweisungen erst, wenn die Aufgabe übereinstimmt. Dadurch kann ein Agent viele Skills verfügbar halten, ohne jede Sitzung von Beginn an aufzublähen.

Anthropics eigene Anleitung macht die beabsichtigte Arbeitsteilung ziemlich klar. CLAUDE.md ist für langlebigen, immer aktiven Projektkontext gedacht. Skills sind für wiederverwendbares Wissen, Spielpläne und aufrufbare Workflows, die bei Bedarf geladen werden sollten. Claude Code hat sogar alte benutzerdefinierte Befehle in denselben Mechanismus integriert, sodass veraltete .claude/commands/*.md-Dateien weiterhin funktionieren, aber Skills sind jetzt die bessere langfristige Form – und der am besten wiederverwendbare Baustein in jedem KI-gestützten Entwicklungsworkflow.

Wann Claude Skills verwenden: CLAUDE.md vs. Skills vs. Hooks

Ein Claude Skill lohnt sich, wenn Sie sich ständig dieselbe Checkliste, denselben Bereitstellungsplan, dieselbe Code-Review-Richtlinie oder dieselben Fallstricke der internen API in den Chat kopieren. Anthropic empfiehlt ausdrücklich die Erstellung eines Skills, wenn Sie dasselbe Verfahren immer wieder wiederverwenden oder wenn ein Abschnitt von CLAUDE.md zu einem Prozess statt zu einer Tatsache herangewachsen ist. Das ist die praktische Antwort auf die FAQ-Frage: “Was ist ein Claude Skill und wann sollte man ihn verwenden?”. Verwenden Sie einen Skill für wiederholbare Verfahren, nicht für allgemeinen Geschmack oder breite Repository-Regeln.

Der eigentliche Gewinn ist die Kontrolle über Kontextkosten und Verhalten. Ein guter Skill wird nur bei Relevanz geladen, während ein aufgeblähtes CLAUDE.md in jeder Sitzung geladen wird. Anthropic empfiehlt, CLAUDE.md kurz zu halten und Domänenwissen oder Verfahren in Skills zu verlagern, genau weil das bedarfsgerechte Laden den Agenten auf die vorliegende Aufgabe fokussiert.

Meine persönliche Regel ist einfach. Wenn die Anweisung in jeder einzelnen Sitzung gelten soll, gehört sie in CLAUDE.md. Wenn die Anweisung eine wiederverwendbare Methode, Checkliste oder ein Workflow ist, der nur manchmal relevant ist, gehört sie in einen Skill. Wenn die Aktion automatisch bei jedem passenden Ereignis ausgelöst werden muss, gehört sie wahrscheinlich in einen Hook, nicht in einen Skill. Die Funktionsübersicht von Anthropic rahmt diese Tools in fast genau diesem Schichtenmodell ein.

Ein praktischer Indikator für jede Kategorie: Wenn Sie sich selbst dabei ertappen, dieselben Anweisungen in jeden Chat zu kopieren, ist das ein Skill. Wenn ein CLAUDE.md-Abschnitt zu einem Schritt-für-Schritt-Prozess herangewachsen ist, extrahieren Sie ihn in einen Skill. Wenn Sie möchten, dass etwas jedes Mal, wenn eine Datei gespeichert wird, still abfeuert, schreiben Sie stattdessen einen Hook.

Claude Skills IDE-Unterstützung: VS Code, JetBrains, Cursor und Codex

Claude Code läuft über CLI, Desktop, VS Code, JetBrains, Web und mobile Remote-Control-Flows. Anthropic beschreibt die CLI als die vollständigste lokale Oberfläche, während die IDE-Integrationen einige CLI-exklusive Funktionen gegen ein editor-eigenes Review, Dateikontext und ergonomischere Workflow-Integration tauschen. Konfiguration, Projektgedächtnis und MCP-Server werden über die lokalen Oberflächen hinweg geteilt, sodass Ihre .claude-Konfiguration Sie begleitet und nicht in einem Editor gefangen ist.

Für VS Code besagt Anthropic, dass die Erweiterung die empfohlene Schnittstelle innerhalb des Editors ist. Sie bietet Plan-Reviews, Inline-Diffs, Unterstützung für Dateierwähnungen und integrierten Zugriff auf die CLI. Der gleiche Installationsablauf bietet auch einen direkten Pfad für Cursor. Für JetBrains umfasst die aktuelle unterstützte Liste IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm und GoLand, mit integrierten Funktionen für Diff-Ansichten, Auswahlfreigabe, Dateireferenz-Verknüpfungen und Diagnosefreigabe.

Die JetBrains-Unterstützung ist besser, als viele Entwickler erkennen. Wenn Sie claude aus der integrierten Terminalumgebung der IDE ausführen, sind die Integrationsfunktionen automatisch aktiv. Wenn Sie von einem externen Terminal aus starten, dokumentiert Anthropic den /ide-Befehl, um Claude Code wieder mit der JetBrains-Sitzung zu verbinden, und empfiehlt ausdrücklich den Start aus demselben Projektstammverzeichnis, damit Claude dieselben Dateien sieht wie Ihre IDE. Wenn Sie in JetBrains Automatik-Editiermodi verwenden, warnt Anthropic auch, dass IDE-Konfigurationsdateien Teil der bearbeitbaren Oberfläche werden können, sodass manuelle Bestätigungen in dieser Umgebung die sicherere Standardoption sind.

Nun zum größeren Punkt. Claude Skills sind nicht nur eine Sache von Claude Code. Agent Skills ist ein offener Standard. Die offizielle Agent Skills Quickstart sagt, dass derselbe Skill in VS Code mit GitHub Copilot, Claude Code und OpenAI Codex funktionieren kann, und OpenAIs eigene Codex-Dokumente besagen, dass Skills in der Codex-CLI, der IDE-Erweiterung und der App verfügbar sind. Die Implementierungsanleitung für Agent Skills fügt ein wichtiges Portabilitätsdetail hinzu: .agents/skills hat sich als Cross-Client-Konvention etabliert, während einige Clients auch .claude/skills für pragmatische Kompatibilität durchsuchen.

Hier ist also die praktische Kompatibilitätsregel, die ich empfehle. Wenn Sie zunächst und ausschließlich für Claude Code entwickeln, erstellen Sie in .claude/skills. Wenn Sie echte Cross-Client-Portabilität wünschen, zielen Sie auf die offene Agent Skills-Form ab und verwenden Sie .agents/skills als kanonischen Pfad. Geben Sie nicht vor, dass diese beiden Ziele identisch sind. Sie sind verwandt, nicht identisch.

Kurze Kompatibilitätsreferenz:

SKILL.md Dateistruktur, Ordnerlayout und Speicherorte

Ein ordentlicher Skill ist ein Ordner, keine zufällige Markdown-Datei im Repository-Stammverzeichnis. Die Kernspezifikation erfordert ein Verzeichnis mit einer SKILL.md-Datei und erlaubt optionale scripts/, references/ und assets/-Verzeichnisse. SKILL.md muss YAML-Frontmatter gefolgt von Markdown-Anweisungen enthalten. In der Spezifikation sind name und description erforderlich, name ist auf 64 Zeichen mit Kleinbuchstaben, Zahlen und Bindestrichen beschränkt, compatibility dient nur realen Umgebungsanforderungen und allowed-tools ist in allen Implementierungen ausdrücklich experimentell.

Claude Code ist etwas lockerer als die portable Spezifikation, da es einen Namen aus dem Verzeichnis ableiten und bei fehlender description auf den ersten Absatz zurückgreifen kann. Darauf sollten Sie nicht verlassen, wenn Ihnen Portabilität oder Vorhersehbarkeit wichtig sind. Claude.ai erfordert, dass der Verzeichnisname mit dem name-Feld übereinstimmt, und der Upload-Pfad für benutzerdefinierte Skills begrenzt Beschreibungen auf 200 Zeichen, obwohl die breitere Spezifikation viel mehr zulässt. Die portable Wahl ist, einen expliziten name festzulegen, das Verzeichnis identisch zu halten und eine präzise Beschreibung zu schreiben, die in enge Grenzen passt. Das beantwortet das FAQ-Thema “Was sollte eine SKILL.md-Datei enthalten” ohne vage Ausflüchte.

Beginnen Sie mit einer Struktur, die so langweilig ist:

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Wenn Portabilität über Skills-kompatible Clients wichtiger ist als Claude Code-Bequemlichkeit, behalten Sie die gleiche interne Struktur bei und tauschen Sie .claude/skills/ gegen .agents/skills/ aus. Die Ordnerstruktur ist auf jeden Fall das gleiche Prinzip.

Für Claude Code sind die Speicherorte geradlinig. Projekte Skills leben bei .claude/skills/<skill-name>/SKILL.md. Persönliche Skills leben bei ~/.claude/skills/<skill-name>/SKILL.md. Plugin-verteilte Skills leben unter <plugin>/skills/<skill-name>/SKILL.md. Anthropic dokumentiert die Priorität über die integrierten Bereiche als Unternehmen über persönlich über Projekt, während Plugin-Skills Kollisionen vermeiden, indem sie eine namensraum-basierte Form wie plugin-name:skill-name verwenden. Unter Windows löst ~/.claude zu %USERPROFILE%\.claude auf, und CLAUDE_CONFIG_DIR kann das gesamte Basisverzeichnis neu positionieren.

Die Wahl zwischen Projekt- und persönlichem Bereich ist geradlinig. Verwenden Sie .claude/skills/ innerhalb des Repos, wenn der Skill eng mit dieser Codebasis gekoppelt ist – zum Beispiel ein Bereitstellungsplan, der Ihre spezifischen Cluster-Namen kennt, oder eine Review-Richtlinie, die auf den Konventionen Ihres Teams abgestimmt ist. Verwenden Sie ~/.claude/skills/ für Skills, die Sie über Projekte hinweg begleiten: persönliche Checklisten, generische Changelog-Generatoren, bevorzugte Debugging-Workflows. Alles, was Sie in ein Dotfiles-Repository stellen würden, gehört in den persönlichen Bereich.

Einige scharfe Kanten sind wertvoll, sich zu merken. SKILL.md muss genau mit dieser Groß-/Kleinschreibung benannt sein. Anthropics PDF-Leitfaden empfiehlt kebab-case-Ordnernamen und sagt ausdrücklich, keine README.md in den Skill-Ordner zu legen, weil die operative Dokumentation in SKILL.md oder references/ leben sollte. Derselbe Leitfaden betont auch, dass die Benennung von SKILL.md groß-/kleinschreibungsempfindlich ist. Das sind langweilige Einschränkungen, aber langweilige Einschränkungen machen Tools zuverlässig.

Claude Code tut auch das Richtige für Monorepos. Es entdeckt automatisch verschachtelte .claude/skills/-Verzeichnisse, wenn Sie in Unterordnern arbeiten, was ideal für Paket- oder Dienstebene-Skills ist. Es überwacht auch bestehende Skill-Verzeichnisse auf Live-Änderungen während der aktuellen Sitzung. Die eine Neustart-Falle ist die Erstellung eines obersten Skill-Verzeichnisses, das beim Sitzungsstart nicht existierte. Anthropic dokumentiert dies als den Fall, in dem Sie einen Neustart benötigen, damit das neue Verzeichnis überwacht werden kann.

Claude Skills Best Practices: Beschreibungen, Skripte und Bereich

Der schnellste Weg, einen nutzlosen Skill zu erstellen, ist, ein LLM zu bitten, einen aus generischem Trainingswissen zu erfinden. Anthropics Best-Practices-Leitfaden warnt genau davor. Die wertvollen Teile sind die domänenspezifischen Korrekturen, Randfälle, Tool-Wahlen und Konventionen, die das Modell nicht zuverlässig selbst erfinden würde. Der richtige Workflow ist, die Aufgabe einmal mit dem Agenten zu lösen, sie zu korrigieren, bis sie funktioniert, und dann die Methode in einen Skill zu extrahieren.

Bereichen Sie den Skill wie eine gute Funktion, nicht wie eine Wiki-Seite. Anthropic sagt, Skills sollten eine kohärente Arbeitseinheit kapseln. Zu eng, und Sie zwingen mehrere Skills, sich für eine Aufgabe zu stapeln. Zu breit, und der Agent kann sie nicht präzise aktivieren. Der Best-Practices-Leitfaden ist unmissverständlich, dass übermäßig umfassende Skills mehr schaden als nutzen, weil das Modell irrelevante Anweisungen jagt und das Signal verliert.

Die Qualität der Beschreibung ist kein kosmetisches Anliegen. Es ist die Routing-Schicht. Sowohl Anthropic als auch die Agent Skills-Dokumente sagen, dass das description-Feld der primäre Mechanismus ist, den das Modell verwendet, um zu entscheiden, ob überhaupt ein Skill geladen wird. Gute Beschreibungen sagen, was der Skill tut, wann er verwendet werden soll und welche Auslöserphrasen oder Dateitypen ein Benutzer tatsächlich erwähnen würde. Schlechte Beschreibungen sind vage, übermäßig technisch oder breit genug, um Unsinn zu treffen. Das ist die echte Antwort auf die FAQ-Frage: “Warum wird ein Claude Skill nicht ausgelöst?”. Meistens ist der Router schlecht, nicht das Modell.

Der Kontrast ist nebeneinander klar:

Schlechte Beschreibungen — zu vage für zuverlässiges Routing:

• Hilft bei Code-Reviews — trifft alles, unterscheidet nichts
• Nützlich für Entwicklungsaufgaben — breiter als eine Suchanfrage
• Unterstützt beim Schreiben — kein Router, nur eine Kategorie-Etikette

Gute Beschreibungen — spezifische Auslöser-Sprache:

• Review Pull Requests auf Sicherheitsprobleme, Migrationsrisiken und fehlende Tests. Verwenden Sie beim Review eines PR, git diff oder release-kritischer Änderung.
• Generieren Sie ein Changelog aus git log-Ausgabe. Verwenden Sie bei der Vorbereitung eines Releases, beim Schreiben von Release-Notes oder bei der Zusammenfassung von Commits seit dem letzten Tag.
• Scaffolden Sie einen neuen Go HTTP-Handler mit Request-Validierung und Error-Middleware. Verwenden Sie beim Hinzufügen eines neuen Endpoints oder einer Route zu einem Go-Service.

Das Muster ist jedes Mal gleich: Stellen Sie fest, was der Skill tut, benennen Sie die genauen Benutzerphrasen, die ihn aktivieren sollten, und nennen Sie optional relevante Dateitypen oder Tools. Wenn Ihre Beschreibung eine generische Google-Suchanfrage treffen würde, ist sie nicht spezifisch genug.

Wenn ein Workflow Nebeneffekte hat, machen Sie ihn manuell. Claude Code stellt das direkt zur Verfügung. disable-model-invocation: true macht einen Skill nur benutzeraufrufbar, was Anthropic für Aktionen wie Deploys, Commits oder ausgehende Nachrichten empfiehlt. user-invocable: false geht den anderen Weg und versteckt den Skill im Slash-Menü, während es Claude trotzdem erlaubt, ihn als Hintergrundwissen zu verwenden. Das beantwortet das FAQ-Thema “Wann sollte ein Skill manuell statt automatisch sein” in einem Satz: manuell für Risiken, automatisch für sichere, wiederholbare Anleitung.

Halten Sie SKILL.md klein genug, um verständlich zu bleiben. Anthropic empfiehlt, es unter 500 Zeilen und um die 5.000 Tokens zu halten und detailliertes Material in references/ oder ähnliche Dateien mit expliziten Ladeanweisungen zu verlagern. “Lies references/api-errors.md, wenn die API einen Nicht-200-Code zurückgibt” ist ein gutes Muster. “Siehe references/” ist faul. Claude Code injiziert auch den gerenderten Skill als Nachricht in das Gespräch und liest die Datei bei späteren Runden nicht immer wieder neu. Nach Kontext-Kompaktierung wird nur aktueller Skill-Inhalt innerhalb der Token-Budgets weitergetragen. Riesige Skills sind daher nicht nur hässlich. Sie sind über lange Sitzungen hinweg zerbrechlich.

Ein gutes SKILL.md kann sehr einfach bleiben:

---
name: review-pr
description: Review Pull Requests auf Sicherheitsprobleme, Migrationsrisiken und fehlende Tests. Verwenden Sie beim Review eines PR, git diff oder release-kritischer Änderung.
compatibility: Designed for Claude Code. Requires git and gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Review PR

Lies references/checklist.md, bevor du Befehle ausführen.

1. Sammle den Diff und geänderte Dateien.
2. Markiere Probleme hinsichtlich Korrektheit, Sicherheit und Testabdeckung.
3. Gib Befunde gruppiert nach Schweregrad mit Dateireferenzen zurück.
4. Schlage zuerst die kleinste sichere Korrektur vor.

Verwenden Sie Skripte, wenn Determinismus wichtiger ist als Eloquenz. Der Skills-Skript-Leitfaden ist hier hervorragend. Er sagt, dass agentenorientierte Skripte interaktive Prompts vermeiden, die Nutzung über --help dokumentieren, hilfreiche Fehlermeldungen ausgeben, strukturierte Ausgabe wie JSON oder CSV auf stdout bevorzugen, Diagnosen an stderr senden und den wiederholungs sicheren Einsatz unterstützen sollen. Er empfiehlt auch, Einmal-Tool-Versionen zu pinnen und Laufzeitanforderungen explizit in SKILL.md oder dem compatibility-Feld zu beschreiben, anstatt anzunehmen, dass die Umgebung die richtigen Pakete hat.

Ein minimales, aber korrektes agentenorientiertes Skript sieht so aus:

#!/usr/bin/env bash
# scripts/collect-diff.sh — aufgerufen durch review-pr skill
# Usage: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Strukturierte Ausgabe auf stdout, damit der Agent sie parsen kann
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

Drei Dinge machen dies agentensicher. set -euo pipefail stellt sicher, dass das Skript bei jedem Fehler laut beendet wird, anstatt still fortzufahren. JSON auf stdout gibt dem Agenten ein Format, das er ohne Raten parsen kann. Diagnosen gehen an stderr, damit der stdout-Stream des Agenten sauber bleibt. Nichts davon ist clever. Alles davon ist notwendig.

Eine subtile Falle ist allowed-tools. In der Spezifikation ist es experimentell und die Unterstützung variiert. In Claude Code genehmigt es spezifische Tools, während der Skill aktiv ist, schränkt es aber das Universum der aufrufbaren Tools nicht ein, und Verweigerungsregeln gehören weiterhin in die Claude Code-Berechtigungen. In der Claude Agent SDK sagt Anthropic ausdrücklich, dass das allowed-tools-Frontmatter in SKILL.md nicht gilt, sodass SDK-Apps den Tool-Zugriff in der Hauptkonfiguration allowed_tools oder allowedTools erzwingen müssen. Wenn Sie diesen Unterschied ignorieren, wird sich Ihr Skill in der CLI und in SDK-gestützter Automatisierung anders verhalten.

Ein weiteres fortgeschrittenes Muster ist wert, gestohlen zu werden. Wenn ein Workflow Ihren Hauptthread mit Logs, Dateisuchen oder langen Forschungsausgaben überfluten würde, lässt Claude Code einen Skill in einem gegabelten Subagenten mit context: fork und einem agent wie Explore laufen. Anthropic zeigt dies für Forschungsworkflows, wo die schwere Arbeit in isoliertem Kontext stattfindet und das Hauptgespräch die Zusammenfassung erhält. Für tiefe Codebase-Erkundung ist das ein viel besseres Design als ein riesiger Inline-Skill, der die Hauptsitzung verschmutzt.

Ein gegabelter Skill sieht im Frontmatter so aus:

---
name: explore-codebase
description: Tiefgehende Erkundung einer unbekannten Codebasis. Verwenden Sie bei der Onboarding in ein neues Repo, Audit der Architektur oder Mapping von Modulabhängigkeiten.
context: fork
agent: Explore
compatibility: Requires Claude Code CLI.
---
# Explore Codebase

1. Durchwandern Sie den Verzeichnisbaum und fassen Sie die obersten Module zusammen.
2. Identifizieren Sie die Haupteintrittspunkte und ihre Verantwortlichkeiten.
3. Zeichnen Sie den Abhängigkeitsgraphen zwischen Paketen auf.
4. Geben Sie eine strukturierte Zusammenfassung an die Hauptsitzung zurück — nicht die rohe Dateiliste.

Die Zeile context: fork ist der Schlüssel. Ohne sie landet die Erkundungsausgabe inline in Ihrem Gespräch. Mit ihr läuft der Subagent in seinem eigenen Kontextfenster und gibt eine Zusammenfassung zurück. Der Unterschied zählt bei großen Repos, wo allein die Erkundung Tausende von Tokens verbrauchen kann.

Testen von Claude Skills: Auslöser, Korrektheit und Basisvergleiche

Ein Skill wird nicht getestet, weil einmal ein Happy-Path-Demo funktioniert hat. Anthropics Leitfaden unterteilt das Testen in drei Ebenen: manuelles Testen in Claude.ai, skriptgestütztes Testen in Claude Code und programmatisches Testen über die Skills-API. Die empfohlenen Evaluierungsbereiche sind Auslöser, funktionale Korrektheit und Leistung im Vergleich zu einer Basislinie ohne den Skill. Das ist auch die beste Antwort auf die FAQ-Frage: “Wie testet man, ob ein Skill zuverlässig ist?”. Sie testen die Routenwahl, die Ausgabequalität und die Effizienz, nicht nur, ob das Modell selbstbewusst klang.

Die offizielle Evaluierungsanleitung gibt eine klare Struktur für Testfälle. Jeder Fall sollte eine realistische Benutzeranfrage, eine für Menschen lesbare Beschreibung der erwarteten Ausgabe und optionale Eingabedateien enthalten. Die Dokumente speichern diese in evals/evals.json innerhalb des Skill-Verzeichnisses, was eine sinnvolle Konvention ist, auch wenn Sie Ihr eigenes Gerüst bauen.

Verwenden Sie eine Fixtur-Datei und ein nüchternes Evaluierungs-Layout wie folgt:

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Review diesen PR auf Sicherheitsprobleme und fehlende Tests",
      "expected_output": "Befunde gruppiert nach Schweregrad mit Dateireferenzen und mindestens einer Testempfehlung.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Fasse die Commits der letzten Woche zusammen",
      "expected_output": "Der Skill sollte nicht aktiviert werden.",
      "files": []
    }
  ]
}

Meine eigene Testregel ist härter als die meisten Teams verwenden, aber sie stimmt mit der offiziellen Anleitung überein. Jeder ernsthafte Skill sollte Soll-auslösen-Abfragen, Soll-nicht-auslösen-Abfragen, mindestens einen Randfall-Test und einen Basisvergleich ohne den Skill haben. Anthropics Beispiele vergleichen Tool-Aufrufe, fehlgeschlagene API-Aufrufe, Klärungsschleifen und Token-Nutzung mit und ohne den Skill, weil “funktioniert” nicht dasselbe ist wie “verbessert den Workflow”.

Wenn Sie über das Claude Agent SDK testen, denken Sie an die Verkabelung. Skills sind dort Dateisystem-Artefakte, keine programmatischen Registrierungen. Anthropic sagt, Sie müssen das "Skill"-Tool aktivieren und die relevanten Dateisystem-Einstellungen über settingSources oder setting_sources laden. Wenn Sie user oder project weglassen oder cwd an den falschen Ort zeigen, wird das SDK den Skill nicht entdecken. Anthropic empfiehlt sogar, “Welche Skills sind verfügbar?” als direkte Entdeckungsprüfung zu fragen.

Testen Sie auch auf dem Modell und Client, auf dem Sie tatsächlich liefern wollen. Die offene Agent Skills Quickstart warnt ausdrücklich, dass die Zuverlässigkeit der Tool-Nutzung über Modelle hinweg variiert und einige Modelle direkt antworten können, anstatt den Befehl auszuführen, den der Skill beabsichtigt. Das ist nicht immer ein Skill-Designproblem. Manchmal ist es ein Modell-Auswahlproblem, und Ihre Testmatrix sollte es aufdecken.

Claude Skills Fehlerbehebung: Häufige Fehler und Lösungen

Wenn ein Skill falsch funktioniert, gehen Sie von Verpackung vor Intelligenz aus. Die häufigsten Fehler sind immer noch die langweiligen.

• Wenn der Skill überhaupt nicht gefunden wird, überprüfen Sie, ob die Datei genau SKILL.md heißt, mit der richtigen Groß-/Kleinschreibung, im richtigen Verzeichnis. Anthropics Fehlerbehebungsleitfaden nennt den Dateinamen mit Groß-/Kleinschreibung explizit, und seine Claude Code- und SDK-Dokumente weisen Sie direkt auf .claude/skills/*/SKILL.md und ~/.claude/skills/*/SKILL.md als erste Checks hin.
• Wenn Frontmatter ungültig ist, überprüfen Sie zuerst die YAML-Delimiter und Anführungszeichen. Anthropics Beispiele zeigen die klassischen Fehler: fehlende ---, nicht geschlossene Anführungszeichen oder ungültige Namen mit Leerzeichen und Großbuchstaben. Skill-Namen sollten klein und mit Bindestrichen getrennt sein.
• Wenn der Skill existiert, aber nicht ausgelöst wird, ist die Beschreibung meist zu vage. Claude Codes eigene Fehlerbehebung sagt, Schlüsselwörter einzubeziehen, die Benutzer natürlich sagen würden, zu überprüfen, ob der Skill erscheint, wenn Sie fragen “Welche Skills sind verfügbar?”, und zu versuchen, näher an die Beschreibung zu paraphrasieren. Anthropics PDF-Leitfaden fügt einen großartigen Diagnose-Trick hinzu: Fragen Sie Claude, wann er den Skill verwenden würde, und hören Sie zu, wie er die Beschreibung für Sie umformuliert.
• Wenn der Skill zu oft ausgelöst wird, verengen Sie den Bereich. Anthropic empfiehlt, die Beschreibung spezifischer zu machen, negative Auslöser hinzuzufügen und disable-model-invocation: true für Workflows zu verwenden, die Sie nur durch expliziten Befehl wollen. Zu häufiges Auslösen ist meist nur unter-spezifizierte Routing-Sprache.
• Wenn der Skill scheint, in langen Sitzungen an Einfluss zu verlieren, denken Sie daran, dass Beschreibungen im Claude Code-Katalog verkürzt werden können, wenn viele Skills vorhanden sind, und aufgerufene Skills später innerhalb der Token-Budgets nach Kompaktierung mitgeführt werden. Anthropic empfiehlt, Schlüsselwörter in der Beschreibung voranzustellen, überflüssigen Text zu kürzen und für Claude Code spezifisch SLASH_COMMAND_TOOL_CHAR_BUDGET anzupassen, wenn Beschreibungslisten zu aggressiv gequetscht werden.
• Wenn ein gebündeltes Skript hängt oder unvorhersehbar verhält, überprüfen Sie, ob es interaktive Eingaben erwartet. Der Skript-Leitfaden sagt, dass Agenten in nicht-interaktiven Shells laufen, sodass TTY-Prompts, Passworteingaben und Bestätigungsmenüs Design-Fehler sind. Akzeptieren Sie Eingaben über Flags, Umgebungsvariablen oder stdin und machen Sie Fehler explizit.
• Wenn das SDK Ihren Skill nicht sieht, bestätigen Sie, dass allowed_tools "Skill" enthält, dass settingSources oder setting_sources user und/oder project enthält und dass cwd auf das Verzeichnis zeigt, das tatsächlich .claude/skills/ enthält. Ohne diese Einrichtung ist das Skill-System nicht aktiviert, egal wie korrekt Ihre Markdown-Dateien aussehen.
• Wenn ein MCP-gestützter Skill lädt, aber die Tool-Aufrufe fehlschlagen, ist Anthropics Fehlerbehebungscheckliste sinnvoll: Überprüfen Sie, ob der MCP-Server verbunden ist, bestätigen Sie Authentifizierung und Bereiche, testen Sie das MCP-Tool direkt ohne den Skill und überprüfen Sie die genauen Tool-Namen, da sie groß-/kleinschreibungsempfindlich sind.

Die langweilige Wahrheit ist, dass gute Claude Skills wie guter operativer Engineering aussehen. Klare Namen. Kleine Dateien. Explizite Auslöser. Deterministische Skripte, wo nötig. Echte Tests. Wenn Ihr Skill wie ein knackscharfes Runbook liest, hat der Agent eine Chance. Wenn er wie ein Brainstorming liest, haben Sie einfach nur Chaos in einem Ordner versteckt.