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

Die meisten Teams missbrauchen Claude Skills auf eine von zwei Arten. Entweder verwandeln sie SKILL.md in einen Mülldeponie-Ort oder sie schaffen es nie, von riesigen kopierten Prompts wegzukommen.

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

Claude Skills sind Verzeichnisse, die durch SKILL.md verankert sind, mit optionalen Skripten, Referenzen und Assets. Sie funktionieren aufgrund der progressiven Offenlegung. Der Agent beginnt damit, nur kompakte Metadaten wie den Skill-Namen und die Beschreibung zu laden, und liest die vollständigen Anweisungen erst, wenn die Aufgabe passt. Das ermöglicht es einem Agenten, viele Skills verfügbar zu halten, ohne jede Sitzung von Anfang an aufzublähen.

Wenn Sie auch Hermes Agent betreiben, entspricht die gleiche Form auf der Festplatte der von Hermes dokumentierten agentskills-Stil-Spezifikation – bedingte Aktivierung, Hub-Scanning und das Verhältnis von Secrets zu Config werden in Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices detailliert beschrieben.

Die eigenen Leitlinien von Anthropic machen die beabsichtigte Arbeitsteilung ziemlich klar. CLAUDE.md ist für dauerhaften, stets aktiven Projektkontext gedacht. Skills sind für wiederverwendbares Wissen, Playbooks und aufrufbare Workflows gedacht, die bei Bedarf geladen werden sollen. Das macht Skills zum natürlichen Ort, um einen spec-getriebenen Entwicklungszyklus zu kodifizieren – spezifizieren, planen, implementieren, validieren – wenn Sie mehr Struktur als bei Vibe Coding, aber weniger Zeremonie als bei einem vollständigen Spec Kit-Gerüst wünschen. Siehe GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows, um zu sehen, wie Claude Code Skills im Vergleich zu portablen und IDE-integrierten Alternativen abschneiden. Wenn Sie diesen Zyklus lieber vorgebaut und erzwungen installieren, als ihn selbst zu erstellen, paketiert Superpowers genau diesen Art Skill-Stack – Brainstorming, Planung, Subagent-Review, TDD – als installierbares Plugin.

Claude Code hat sogar alte benutzerdefinierte Befehle in denselben Mechanismus integriert, so dass Legacy-Dateien wie .claude/commands/*.md weiterhin funktionieren, aber Skills sind jetzt die bessere langfristige Form – und der wiederverwendbarste Baustein in jedem KI-gestützten Entwicklungsworkflow.

Wann man Claude Skills verwendet: CLAUDE.md vs. Skills vs. Hooks

Ein Claude Skill ist die Erstellung wert, wenn Sie dieselbe Checkliste, dasselbe Deployment-Playbook, dieselbe Code-Review-Rubrik oder dieselben internen API-Fallen immer wieder in den Chat einfügen. Anthropic empfiehlt ausdrücklich, einen Skill zu erstellen, wenn Sie dasselbe Verfahren immer wieder verwenden, 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 einen verwenden". Verwenden Sie einen Skill für wiederholbare Verfahren, nicht für allgemeinen Geschmack oder breite Repo-Regeln.

Der eigentliche Gewinn liegt in der Kontrolle über Kontextkosten und Verhalten. Ein guter Skill wird nur geladen, wenn er relevant ist, 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, gerade weil das Laden bei Bedarf den Agenten darauf konzentriert, was vor ihm liegt.

Meine meinungsstarke 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 wichtig ist, gehört sie in einen Skill. Wenn die Aktion automatisch bei jedem passenden Ereignis erfolgen muss, gehört sie wahrscheinlich in einen Hook, nicht in einen Skill. Die Funktionsübersicht von Anthropic rahmt diese Tools in fast genau diesem Ebenenmodell ein.

Ein praktischer Geruch für jede Ebene: Wenn Sie feststellen, dass Sie dieselben Anweisungen in jeden Chat einfügen, 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 still und leise jedes Mal ausgelöst wird, wenn eine Datei gespeichert wird, schreiben Sie stattdessen einen Hook. Es gibt auch eine vierte Ebene, die es zu kennen gilt: Wenn eine Aufgabe eine Menge lärmender Zwischenausgaben erzeugt, die Sie nicht im Hauptsitzungsraum haben möchten – Codebase-Erkundung, ein großer Testlauf – dann ist das eine Aufgabe für einen Subagent, nicht für einen Skill.

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

Claude Code läuft über CLI, Desktop, VS Code, JetBrains, Web und mobile ferngesteuerte Workflows. Anthropic beschreibt die CLI als die vollständigste lokale Oberfläche, während die IDE-Integrationen einige nur in der CLI verfügbare Funktionen gegen editor-native Reviews, Dateikontext und engere Workflow-Ergonomie eintauschen. Konfiguration, Projektspeicher und MCP-Server werden über die lokalen Oberflächen hinweg geteilt, so dass Ihr .claude-Setup Sie begleitet, anstatt in einem Editor gefangen zu sein.

Für VS Code sagt Anthropic, dass die Erweiterung die empfohlene Schnittstelle innerhalb des Editors ist. Sie bietet Plan-Reviews, Inline-Diffs, Dateierwähnungsunterstützung und integrierten Zugriff auf die CLI. Der gleiche Installationsfluss bietet auch einen direkten Pfad für Cursor. Für JetBrains umfasst die aktuelle Unterstützungsliste IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm und GoLand, mit Diff-Ansicht, Auswahlfreigabe, Dateireferenz-Shortcuts und Diagnosefreigabe, die in das Plugin integriert sind.

Die JetBrains-Unterstützung ist besser, als viele Entwickler denken. Wenn Sie claude aus dem integrierten Terminal 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 mit der JetBrains-Sitzung zu verbinden, und empfiehlt ausdrücklich, von derselben Projektwurzel aus zu starten, damit Claude dieselben Dateien sieht wie Ihre IDE. Wenn Sie Auto-Bearbeitungsmodi in JetBrains verwenden, warnt Anthropic auch, dass IDE-Konfigurationsdateien Teil der bearbeitbaren Oberfläche werden können, so dass manuelle Genehmigungen in dieser Umgebung der sicherere Standard sind.

Jetzt der größere Punkt. Claude Skills sind nicht nur eine Claude Code-Sache. Agent Skills ist ein offener Standard. Das 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-Dokumentation sagt, dass Skills im Codex CLI, in der IDE-Erweiterung und in der App verfügbar sind. Der Agent Skills Implementierungsführer fügt ein wichtiges Portabilitätsdetail hinzu: .agents/skills hat sich als die Client-übergreifende Konvention etabliert, während einige Clients auch .claude/skills für pragmatische Kompatibilität scannen.

Hier ist also die praktische Kompatibilitätsregel, die ich empfehle. Wenn Sie nur für Claude Code erstellen und nur das, erstellen Sie in .claude/skills. Wenn Sie wirklich Client-übergreifende Portabilität wollen, 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, aber nicht identisch.

Schnelle Kompatibilitätsreferenz:

Struktur, Verzeichnislayout und Speicherorte der SKILL.md-Datei

Ein ordentlicher Skill ist ein Ordner, keine zufällige Markdown-Datei, die in der Repo-Wurzel liegt. 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 begrenzt und verwendet Kleinbuchstaben, Zahlen und Bindestriche, compatibility ist nur für echte Umgebungsanforderungen gedacht, und allowed-tools ist ausdrücklich experimentell über Implementierungen hinweg.

Claude Code ist etwas lockerer als die portable Spezifikation, da es einen Namen aus dem Verzeichnis ableiten kann und auf den ersten Absatz zurückfällt, wenn description fehlt. Sie sollten sich darauf nicht verlassen, wenn Ihnen Portabilität oder Vorhersehbarkeit wichtig sind. Claude.ai erfordert, dass der Verzeichnisname mit dem name-Feld übereinstimmt, und sein Custom-Skill-Upload-Pfad begrenzt Beschreibungen auf 200 Zeichen, obwohl die breitere Spezifikation viel mehr erlaubt. Die portable Wahl ist, einen expliziten name zu setzen, 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 Ausflüchte zu nehmen.

Beginnen Sie mit einer so langweiligen Struktur:

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

Wenn Portabilität über Skills-kompatible Clients hinweg wichtiger ist als Claude Code-Komfort, behalten Sie die gleiche interne Form bei und tauschen Sie .claude/skills/ gegen .agents/skills/ aus. Die Verzeichnisstruktur ist in beiden Fällen dieselbe Idee.

Für Claude Code sind die Speicherorte geradlinig. Projektskills liegen in .claude/skills/<skill-name>/SKILL.md. Persönliche Skills liegen in ~/.claude/skills/<skill-name>/SKILL.md. Per Plugin verteilte Skills liegen unter <plugin>/skills/<skill-name>/SKILL.md. Anthropic dokumentiert die Priorität über die eingebauten Bereiche hinweg als Enterprise vor Persönlich vor Projekt, während Plugin-Skills Kollisionen vermeiden, indem sie eine namensraum-basierte Form wie plugin-name:skill-name verwenden. Auf Windows wird ~/.claude zu %USERPROFILE%\.claude aufgelöst, und CLAUDE_CONFIG_DIR kann das gesamte Basisverzeichnis verschieben.

Die Wahl zwischen Projekt- und Persönlich-Scope ist geradlinig. Verwenden Sie .claude/skills/ im Repo, wenn der Skill eng an diese Codebase gekoppelt ist – zum Beispiel ein Deployment-Playbook, das Ihre spezifischen Cluster-Namen kennt, oder eine Review-Rubrik, die auf die 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-Repo stellen würden, gehört in den persönlichen Bereich.

Einige scharfe Kanten sind es wert, gemerkt zu werden. SKILL.md muss exakt mit dieser Groß-/Kleinschreibung benannt sein. Der PDF-Leitfaden von Anthropic empfiehlt kebab-case-Verzeichnisnamen und sagt ausdrücklich, keine README.md in den Skill-Ordner zu legen, da die operative Dokumentation in SKILL.md oder references/ gehören sollte. Derselbe Leitfaden betont auch, dass die Benennung von SKILL.md groß-/kleinschreibungssensitiv ist. Das sind langweilige Einschränkungen, aber langweilige Einschränkungen sind das, was Tooling zuverlässig macht.

Claude Code tut auch das Richtige für Monorepos. Es entdeckt automatisch verschachtelte .claude/skills/-Verzeichnisse, wenn Sie in Unterverzeichnissen arbeiten, was ideal für Paket- oder Service-Level-Skills ist. Es beobachtet auch bestehende Skill-Verzeichnisse auf Live-Änderungen während der aktuellen Sitzung. Die eine Neustart-Falle ist die Erstellung eines Top-Level-Skill-Verzeichnisses, das beim Sitzungsstart nicht existierte. Anthropic dokumentiert dies als den Fall, in dem Sie neu starten müssen, damit das neue Verzeichnis beobachtet werden kann.

Claude Skills Best Practices: Beschreibungen, Skripte und Scope

Der schnellste Weg, einen nutzlosen Skill zu erstellen, ist, ein LLM zu bitten, einen aus generischem Trainingswissen zu erfinden. Der Best-Practices-Leitfaden von Anthropic warnt ausdrücklich davor. Die wertvollen Teile sind die domänenspezifischen Korrekturen, Edge Cases, Werkzeugauswahlen und Konventionen, die das Modell nicht zuverlässig allein 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.

Scope den Skill wie eine gute Funktion, nicht wie ein Wiki. Anthropic sagt, Skills sollten eine kohärente Arbeitseinheit kapseln. Zu schmal, 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 offen, dass übermäßig umfassende Skills mehr schaden als nützen, weil das Modell irrelevante Anweisungen verfolgt und das Signal verliert.

Die Qualität der Beschreibung ist keine kosmetische Frage. Sie ist die Routing-Ebene. Sowohl Anthropic als auch die Agent Skills-Dokumentation sagen, dass das description-Feld der primäre Mechanismus ist, den das Modell verwendet, um zu entscheiden, ob es einen Skill überhaupt lädt. Gute Beschreibungen sagen, was der Skill tut, wann man ihn verwenden soll und welche Trigger-Phrasen oder Dateitypen ein Benutzer tatsächlich erwähnen würde. Schlechte Beschreibungen sind vage, übermäßig technisch oder breit genug, um Unsinn zu matchen. 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 klar, wenn man sie nebeneinander stellt:

Schlechte Beschreibungen — zu vage, um zuverlässig zu routen:

• Hilft bei Code-Reviews — matcht alles, disambiguiert nichts
• Nützlich für Entwicklungsaufgaben — breiter als eine Suchanfrage
• Unterstützt das Schreiben — kein Router, nur ein Kategorien-Label

Gute Beschreibungen — spezifische Trigger-Sprache:

• Reviewe Pull Requests auf Sicherheitsprobleme, Migrationsrisiken und fehlende Tests. Verwende bei der Review eines PRs, eines git Diffs oder einer release-kritischen Änderung.
• Erzeuge ein Changelog aus der git log-Ausgabe. Verwende bei der Vorbereitung eines Releases, beim Schreiben von Release Notes oder bei der Zusammenfassung von Commits seit dem letzten Tag.
• Erstelle einen neuen Go HTTP-Handler mit Request-Validierung und Fehler-Middleware. Verwende beim Hinzufügen eines neuen Endpoints oder einer Route zu einem Go-Dienst.

Das Muster ist jedes Mal dasselbe: sagen Sie, was der Skill tut, benennen Sie die exakten Benutzerphrasen, die ihn aktivieren sollten, und benennen Sie optional Dateitypen oder Werkzeuge, die relevant sind. Wenn Ihre Beschreibung eine generische Google-Suchanfrage matchen würde, ist sie nicht spezifisch genug.

Wenn ein Workflow Seiteneffekte hat, machen Sie ihn manuell. Claude Code bietet das direkt an. disable-model-invocation: true macht einen Skill nur für den Benutzer aufrufbar, was Anthropic für Aktionen wie Deploys, Commits oder ausgehende Nachrichten empfiehlt. user-invocable: false geht in die andere Richtung und versteckt den Skill vor dem Slash-Menü, lässt Claude ihn aber weiterhin als Hintergrundwissen verwenden. Das beantwortet das FAQ-Thema „Wann sollte ein Skill manuell statt automatisch sein" in einem Satz: manuell für Risiko, automatisch für sichere, wiederholbare Richtlinien.

Halten Sie SKILL.md klein genug, um verständlich zu bleiben. Anthropic empfiehlt, es unter 500 Zeilen und etwa 5.000 Tokens zu halten und dann detailliertes Material in references/ oder ähnliche Dateien mit expliziten Ladeanweisungen zu verlagern. „Lies references/api-errors.md, wenn die API einen Nicht-200 zurückgibt" ist ein gutes Muster. „Siehe references/" ist faul. Claude Code injiziert auch den gerenderten Skill als Nachricht in den Chat und liest die Datei in späteren Runden nicht erneut. Nach der Kontext-Kompaktierung wird nur der recente Skill-Inhalt innerhalb der Token-Budgets weitergeführt. Riesige Skills sind daher nicht nur hässlich. Sie sind in langen Sitzungen fragil.

Ein gutes SKILL.md kann sehr schlicht bleiben:

---
name: review-pr
description: Reviewe Pull Requests auf Sicherheitsprobleme, Migrationsrisiken und fehlende Tests. Verwende bei der Review eines PRs, eines git Diffs oder einer release-kritischen Änderung.
compatibility: Für Claude Code konzipiert. Erfordert git und gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# PR Reviewen

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

1. Sammle den Diff und die geänderten Dateien.
2. Markiere Korrektheits-, Sicherheits- und Testabdeckungsprobleme.
3. Gib die Ergebnisse nach Schweregrad gruppiert 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 ausgezeichnet. Er sagt, dass agent-gerichtete Skripte interaktive Prompts vermeiden müssen, die Nutzung über --help dokumentieren, hilfreiche Fehlermeldungen ausgeben, strukturierte Ausgabe wie JSON oder CSV auf stdout bevorzugen, Diagnosen an stderr senden und sicher wiederholbare Nutzung unterstützen. Er empfiehlt auch, Einmal-Werkzeugversionen zu fixieren 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 agent-gerichtetes Skript sieht so aus:

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

BASE="${1:?Nutzung: 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 fehlgeschlagen"}\n' >&2; exit 1; }

Drei Dinge machen dies agent-sicher. set -euo pipefail stellt sicher, dass das Skript bei jedem Fehler laut beendet wird, anstatt still weiterzufahren. JSON auf stdout gibt dem Agenten ein Format, das er ohne Ratespiel 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 bestimmte Werkzeuge im Voraus, während der Skill aktiv ist, aber es schränkt das Universum der aufrufbaren Werkzeuge nicht ein, und Verweigerungsregeln gehören weiterhin in die Claude Code-Berechtigungen. Im Claude Agent SDK sagt Anthropic ausdrücklich, dass das allowed-tools-Frontmatter in SKILL.md nicht gilt, so dass SDK-Apps den Werkzeugzugriff in der Hauptkonfiguration allowed_tools oder allowedTools durchsetzen müssen. Wenn Sie diesen Unterschied ignorieren, wird Ihr Skill in der CLI und in SDK-gestützter Automatisierung unterschiedlich funktionieren.

Ein weiteres fortgeschrittenes Muster ist es wert, gestohlen zu werden. Wenn ein Workflow Ihren Hauptthread mit Logs, Dateisuchen oder langer Rechercheausgabe überfluten würde, lässt Claude Code einen Skill in einem geforkten Subagenten ausführen, der context: fork und einen agent wie Explore verwendet. Anthropic zeigt dies für Recherche-Workflows, bei denen die schwere Arbeit in isoliertem Kontext stattfindet und der Hauptchat die Zusammenfassung bekommt. Für tiefe Codebase-Erkundung ist das ein viel besseres Design als ein riesiger Inline-Skill, der die Hauptsitzung verschmutzt.

Ein geforkter Skill sieht im Frontmatter so aus:

---
name: explore-codebase
description: Tiefe Erkundung einer unbekannten Codebase. Verwende beim Onboarding in ein neues Repo, beim Auditieren der Architektur oder beim Kartieren von Modul-Abhängigkeiten.
context: fork
agent: Explore
compatibility: Erfordert Claude Code CLI.
---
# Codebase Erkunden

1. Gehe den Verzeichnisbaum durch und fasse die Top-Level-Module zusammen.
2. Identifiziere die Haupteintrittspunkte und ihre Verantwortlichkeiten.
3. Karte den Abhängigkeitsgraphen zwischen den Paketen.
4. Gib eine strukturierte Zusammenfassung an die Hauptsitzung zurück — nicht die rohe Dateiliste.

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

Claude Skills Testen: Trigger, Korrektheit und Baseline-Vergleiche

Ein Skill wird nicht getestet, weil ein Happy-Path-Demo einmal funktioniert hat. Der Leitfaden von Anthropic unterteilt das Testen in drei Ebenen: manuelles Testen in Claude.ai, skriptbasiertes Testen in Claude Code und programmatisches Testen über die Skills API. Die empfohlenen Bewertungsbereiche sind Auslösung, funktionale Korrektheit und Leistung im Vergleich zu einer Baseline ohne den Skill. Das ist auch die beste Antwort auf die FAQ-Frage „Wie testet man, ob ein Skill zuverlässig ist". Sie testen Routenauswahl, Ausgabequalität und Effizienz, nicht nur, ob das Modell selbstbewusst klang.

Die offizielle Evaluierungsleitlinie gibt eine saubere Struktur für Testfälle. Jeder Fall sollte einen realistischen Benutzerprompt, eine menschenlesbare Beschreibung der erwarteten Ausgabe und optionale Eingabedateien enthalten. Die Dokumente speichern diese in evals/evals.json im Skill-Verzeichnis, was eine sinnvolle Konvention ist, auch wenn Sie Ihr eigenes Harness bauen.

Verwenden Sie eine Fixture-Datei und ein nüchternes Eval-Layout wie dieses:

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Reviewe diesen PR auf Sicherheitsprobleme und fehlende Tests",
      "expected_output": "Ergebnisse nach Schweregrad gruppiert 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 sie verwenden, aber sie stimmt mit der offiziellen Leitlinie überein. Jeder ernsthafte Skill sollte should-trigger-Abfragen, should-not-trigger-Abfragen, mindestens einen Edge-Case-Test und einen Baseline-Vergleich ohne den Skill haben. Die Beispiele von Anthropic vergleichen Werkzeugaufrufe, 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 Verdrahtung. Skills sind dort Dateisystem-Artefakte, keine programmatischen Registrierungen. Anthropic sagt, Sie müssen das "Skill"-Werkzeug aktivieren und die relevanten Dateisystem-Einstellungen über settingSources oder setting_sources laden. Wenn Sie user oder project weglassen oder cwd auf 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, den Sie tatsächlich ausliefern wollen. Das offene Agent Skills Quickstart warnt ausdrücklich, dass die Zuverlässigkeit der Werkzeugnutzung zwischen Modellen variiert, und einige Modelle könnten direkt antworten, anstatt den Befehl auszuführen, den der Skill beabsichtigt. Das ist nicht immer ein Skill-Designproblem. Manchmal ist es ein Modellwahlproblem, und Ihre Testmatrix sollte es aufdecken.

Claude Skills Troubleshooting: Häufige Fehler und Fixes

Wenn ein Skill sich falsch verhält, gehen Sie von Packaging aus, nicht von Intelligenz. Die häufigsten Fehler sind immer noch die langweiligen.

• Wenn der Skill überhaupt nicht gefunden wird, überprüfen Sie, ob die Datei exakt SKILL.md heißt, mit der richtigen Groß-/Kleinschreibung, im richtigen Verzeichnis. Der Troubleshooting-Leitfaden von Anthropic nennt den Dateinamen mit Groß-/Kleinschreibung ausdrücklich, und seine Claude Code- und SDK-Dokumente weisen Sie direkt auf .claude/skills/*/SKILL.md und ~/.claude/skills/*/SKILL.md als erste Prüfungen hin.
• Wenn das Frontmatter ungültig ist, überprüfen Sie zuerst die YAML-Delimiter und Anführungszeichen. Die Beispiele von Anthropic zeigen die klassischen Fehler: fehlendes ---, nicht geschlossene Anführungszeichen oder ungültige Namen mit Leerzeichen und Großbuchstaben. Skill-Namen sollten Kleinbuchstaben und Bindestriche verwenden.
• Wenn der Skill existiert, aber nicht ausgelöst wird, ist die Beschreibung meistens zu vage. Das eigene Troubleshooting von Claude Code sagt, Schlüsselwörter einzufügen, die Benutzer natürlich sagen würden, zu überprüfen, ob der Skill erscheint, wenn Sie fragen „Welche Skills sind verfügbar?", und es zu versuchen, näher an der Beschreibung zu formulieren. Der PDF-Leitfaden von Anthropic fügt einen großartigen Diagnose-Trick hinzu: Fragen Sie Claude, wann es den Skill verwenden würde, und hören Sie zu, wie es die Beschreibung zurückparaphrasiert.
• Wenn der Skill zu oft ausgelöst wird, verengen Sie den Scope. Anthropic empfiehlt, die Beschreibung spezifischer zu machen, negative Trigger hinzuzufügen und disable-model-invocation: true für Workflows zu verwenden, die nur durch expliziten Befehl ausgelöst werden sollen. Über-Auslösung ist meistens nur unter-spezifizierte Routing-Sprache.
• Wenn der Skill in langen Sitzungen den Einfluss zu verlieren scheint, denken Sie daran, dass Beschreibungen im Claude Code-Katalog verkürzt werden können, wenn viele Skills vorhanden sind, und aufgerufene Skills nach der Kompaktierung innerhalb der Token-Budgets weitergeführt werden. Anthropic empfiehlt, Schlüsselwörter in der Beschreibung nach vorne zu stellen, überflüssigen Text zu streichen und, speziell für Claude Code, SLASH_COMMAND_TOOL_CHAR_BUDGET anzupassen, wenn Beschreibungslisten zu aggressiv zusammengedrückt werden.
• Wenn ein gebündeltes Skript hängt oder sich fehlerhaft verhält, überprüfen Sie, ob es interaktive Eingaben erwartet. Der Skript-Leitfaden sagt, dass Agenten in nicht-interaktiven Shells laufen, so dass TTY-Prompts, Passwort-Dialoge und Bestätigungsmenüs Designfehler 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 Ihr Markdown aussieht.
• Wenn ein MCP-gestützter Skill geladen wird, aber die Werkzeugaufrufe fehlschlagen, ist die Troubleshooting-Checkliste von Anthropic sinnvoll: Verifizieren Sie, dass der MCP-Server verbunden ist, bestätigen Sie Authentifizierung und Scopes, testen Sie das MCP-Werkzeug direkt ohne den Skill, und überprüfen Sie dann die exakten Werkzeugnamen, da sie groß-/kleinschreibungssensitiv sind.

Die langweilige Wahrheit ist, dass gute Claude Skills wie gutes operatives Engineering aussehen. Klare Namen. Kleine Dateien. Explizite Trigger. Deterministische Skripte, wo nötig. Echte Tests. Wenn Ihr Skill wie ein knackiges Runbook liest, hat der Agent eine Chance. Wenn er wie ein Brainstorm liest, haben Sie einfach Chaos in einen Ordner versteckt.