Eigenen Claude Skill schreiben: SKILL.md in 10 Minuten

Wir testen Claude Skills beruflich, inzwischen Hunderte davon, und das Muster ist ernüchternd: Die meisten Skills, die bei unserem Review durchfallen, scheitern nicht daran, dass der Autor keine Anleitung schreiben konnte. Sie scheitern, weil der Skill nie geladen wurde, oder weil er lud, wenn er es nicht sollte, oder weil er drei Skills im Trenchcoat war. Alles zur Autorenzeit behebbar, nichts davon im Nachhinein durch ein schöneres README zu retten.

Das ist das Tutorial, von dem wir uns wünschen, jeder Einreicher hätte es zuerst gelesen. Am Ende hast du einen funktionierenden Skill: eine Code-Review-Checkliste, die Claude über „sieht gut aus, vielleicht diese Variable umbenennen" hinaus treibt, hin zur Prüfung von Grenzfällen, Fehlerpfaden und totem Code. Das ist bewusst ein echtes Beispiel. Der beste Community-Skill in unserer Coding-Kategorie, Code Review Checklist, macht genau das und erreicht 8/10 beim Output. Deiner wird ihn am ersten Tag nicht schlagen, aber du wirst jede Entscheidung nachvollziehen, die der Autor dieses Skills getroffen hat.

Das 10-Minuten-Versprechen stimmt, mit einem Sternchen. Die erste funktionierende Version zu schreiben dauert etwa 10 Minuten. Sie richtig zu testen nochmal 30. Überspring den zweiten Teil, und du landest bei der Hälfte der veröffentlichten Skills, die eine frische Session nicht überleben. Die Obduktion dazu steht in warum die Hälfte der Claude Skills nicht funktioniert, und wir würden deinen lieber nicht zu diesem Datensatz hinzufügen.

Wenn du noch nie einen Skill installiert hast und nicht weißt, was das ist, lies zuerst was Claude Skills sind und wie du sie installierst. Dieser Beitrag setzt voraus, dass du mindestens einen benutzt hast.

Schritt 1: auf einen Job zuschneiden

Bevor du eine Zeile schreibst, entscheide, was dein Skill tut. Dann halbier das.

Der größte Fehler, den wir beim Testen sehen, sind Skills, die alles gleichzeitig wollen. „Hilft bei Code-Qualität" klingt nach vernünftigem Umfang. Ist es nicht. So ein Skill will bei Reviews, Refactors, Testschreiben, Linting-Fragen und Architektur-Debatten triggern, was in der Praxis bedeutet, dass Claude nicht erkennen kann, wann er geladen werden soll – also lädt er unvorhersehbar oder gar nicht. Trigger-Probleme sind laut unserer Methodologie der Grund Nummer eins für einen niedrigen Skill-Score, noch vor schlechten Anweisungen und kaputten Installationen. Nicht weil Triggern der schwierigste Teil des Skill-Schreibens ist, sondern weil Scope-Creep weiter oben den Rest weiter unten unlösbar macht.

Ein Skill, ein Job. Hier der Test: Kannst du den Satz „diesen Skill verwenden, wenn der Nutzer ___ möchte" mit einer einzigen konkreten Verbphrase vervollständigen? „Einen Pull Request oder Diff reviewen" besteht. „Ihren Code verbessern" scheitert. Wenn dein Satz ein „und" oder „oder" enthält, das fachfremde Tätigkeiten verbindet, schreibst du zwei Skills. Schreib zwei Skills. Ordner sind kostenlos.

Für unser Beispiel lautet der Umfang: einen Diff oder PR anhand einer festen Checkliste auf Korrektheitsfehler reviewen, Stil-Nitpicks unterdrücken. Nicht „bei Reviews helfen". Nicht „reviewen und fixen". Reviewen, berichten, aufhören.

Schritt 2: die SKILL.md-Vorlage

Ein Skill ist ein Ordner mit einer Pflichtdatei. Unserer liegt in ~/.claude/skills/ für den persönlichen Gebrauch, oder in .claude/skills/ innerhalb eines Repos, wenn das ganze Team ihn bekommen soll:

review-checklist/
  SKILL.md          ← Pflicht, und oft schon alles, was du brauchst
  reference/        ← optional, wird nur geladen, wenn Claude entscheidet, es zu lesen
  templates/        ← optional, Dateien, auf die deine Anweisungen verweisen

Hier die komplette SKILL.md, die wir bauen werden, kommentiert. Kopier sie, lies dann die Kommentare, denn zwei dieser Zeilen zählen weit mehr als der Rest:

---
# 'name' ist ein Bezeichner: klein geschrieben, mit Bindestrichen, ohne Leerzeichen.
# Claude sieht ihn, aber er steuert NICHT das Triggern.
name: review-checklist

# 'description' ist das EINZIGE, was Claude liest, um zu entscheiden,
# ob dieser Skill geladen wird. Alles unterhalb des Frontmatters
# ist unsichtbar, bis diese Entscheidung gefallen ist. Schreib sie
# wie eine Trigger-Bedingung, nicht wie Marketing-Text.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Code review checklist

When reviewing a diff or PR, work through this checklist in
order. Report only findings; do not fix anything unless asked.

## Procedure

1. Read the full diff before commenting on any line.
2. For each changed function, check:
   - Off-by-one risks at loop bounds and slice indices
   - Null/undefined paths: what happens when inputs are empty?
   - Error handling: are failures swallowed or logged and re-raised?
3. Check for dead code the change creates: unused imports,
   unreachable branches, orphaned helpers.
4. Check concurrency only if the diff touches shared state.
5. Verify new logic has test coverage. Missing tests are a
   finding, not a blocker.

## Reporting rules

- Max 10 findings, ordered by severity. If you found 30,
  report the 10 worst.
- Every finding needs a file, a line reference, and a one-line
  fix suggestion.
- Do NOT report: naming preferences, formatting, comment
  style, or anything a linter would catch.
- If the diff is clean, say so in one sentence. Do not invent
  findings to seem thorough.

Das ist der komplette Skill. Kein Build-Schritt, kein Manifest, keine Registrierung. Session neu starten, und er ist live.

Das Frontmatter hat genau zwei Felder, die zählen. name ist Buchhaltung. description entscheidet alles, und hier ist warum: Claude behält von jedem installierten Skill nur Name und Beschreibung im Kontext. Der Body deiner SKILL.md existiert aus Sicht des Modells gar nicht, bis es deine Beschreibung liest, entscheidet „das passt zu dem, was der Nutzer will", und den Rest lädt. Eine brillante 200-Zeilen-Checkliste hinter einer vagen Beschreibung ist eine brillante 200-Zeilen-Checkliste, die niemand je ausführt. In unserem Scoring-Rubrik wird Triggern genauso stark gewichtet wie Output-Qualität, genau aus diesem Grund. Ein Skill, der in 40 % der Fälle zündet, ist ein Münzwurf mit Zusatzaufwand.

Schritt 3: die Trigger-Beschreibung schreiben

Da die Beschreibung eine Trigger-Bedingung ist, schreib sie auch so. Nenn die Formulierungen, die ein echter Nutzer tippen würde. Nimm den Negativraum mit auf, also die benachbarten Anfragen, bei denen der Skill still bleiben soll.

Nebeneinander, aus echten Einreichungen, die wir getestet haben (leicht anonymisiert):

Schlecht:

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Gut:

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

Die schlechte beschreibt den Nutzen. Die gute beschreibt den Moment. Claude liest deine Beschreibung nicht, um überzeugt zu werden; es gleicht sie mit den tatsächlichen Worten des Nutzers ab. „Review this PR" teilt kein einziges Wort mit „helps improve code quality", also verschläft der Skill seinen eigenen Anwendungsfall. Wir haben eine Einreichung fast identisch zum schlechten Beispiel getestet: Sie zündete bei 1 von 8 review-artigen Prompts. Nach Umschreiben der Beschreibung auf konkrete Formulierungen, bei gleichem Body, zündete sie bei 8 von 8.

Ein weiteres Paar, diesmal zum Negativraum:

Schlecht:

description: Use for anything related to testing.

Gut:

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

„Alles rund um Testing" ist der direkte Weg, eine Debugging-Session zu kapern. Über-Triggern ist leiser als Unter-Triggern und genauso schädlich: Der Nutzer bekommt checklisten-artige Antworten auf Fragen, die etwas anderes gebraucht hätten, gibt dem Modell die Schuld und deinstalliert den Skill.

Mechanische Regeln, die sich über alles bewähren, was wir getestet haben: nenn drei bis fünf konkrete Nutzerformulierungen, füg mindestens eine „NICHT verwenden"-Klausel hinzu, bleib unter etwa 500 Zeichen, und verwende nie die Wörter „powerful", „comprehensive" oder „helps with". Diese Wörter korrelieren in unseren Daten so konsistent mit schlechten Trigger-Scores, dass wir mittlerweile zusammenzucken, wenn wir sie sehen.

Schritt 4: einen Body schreiben, dem Claude tatsächlich folgt

Sobald der Skill lädt, ist der Body das Anweisungsset. Der Fehlermodus hier ist subtiler als beim Triggern, aber genauso häufig: Anweisungen, die inspirieren statt einschränken. „Schreib ein gründliches, durchdachtes Review" ist ein Motivationsposter. Claude will bereits gründlich und durchdacht sein; das ist das Standardverhalten, das du eigentlich formen willst, nicht die Form selbst.

Die Skills, die unsere Rankings anführen, sind Listen von Einschränkungen. Test-Driven Development verbietet Implementierung, bevor ein fehlschlagender Test existiert, ohne Ausnahme. Unser Beispiel-Skill deckelt Findings bei 10 und verbietet Stil-Nitpicks komplett. Beachte, wie viele seiner Zeilen mit „do not" beginnen. Das ist Absicht. Modelle generieren standardmäßig zu viel, also sind die wertvollsten Anweisungen meist subtraktiv.

Faustregeln für den Body:

1. Nummerierte Abläufe schlagen Prosa. „Arbeite das der Reihe nach ab" gibt Claude eine Struktur; Absätze geben nur Stimmung.
2. Nenn die Abbruchbedingung. Unser Skill sagt: Findings berichten, nicht fixen. Ohne diese Zeile fängt Claude hilfsbereit an, den Code umzuschreiben, worum niemand gebeten hat.
3. Leg das Ausgabeformat fest. Maximalanzahlen, Pflichtfelder, wie ein sauberes Ergebnis aussieht. „Wenn der Diff sauber ist, sag das" verhindert erfundene Findings, ein Fehler, den wir bei Review-Skills ständig sehen.
4. Pack selten benötigte Details in reference/-Dateien. Wenn dein Skill einen 300-Zeilen-Styleguide hat, der einmal im Monat greift, füg ihn nicht in die SKILL.md ein, wo er bei jeder Aktivierung Kontext verbrennt. Speicher ihn als reference/style-guide.md und schreib „wenn der Nutzer nach X fragt, lies zuerst reference/style-guide.md". Claude lädt sie bei Bedarf.

Wann fügst du Skripte und Templates hinzu? Nur, wenn Anweisungen den Job nicht erledigen können. Ein Skill, der eine bestimmte Konfigurationsdatei erzeugt, sollte ein templates/config.yaml mitliefern und sagen „kopier das, dann passe es an". Ein Skill, der deterministisches Verhalten braucht, etwa das Parsen eines Lockfile-Formats, sollte ein Skript mitliefern und Claude anweisen, es auszuführen statt es jedes Mal aus dem Gedächtnis neu zu implementieren. Aber die meisten Skills brauchen keins von beidem. Unser Beispiel braucht keins von beidem. Jede Datei im Ordner ist etwas, das du jetzt pflegst, also verdien dir jede einzelne.

Schritt 5: lokal testen

Du bist nicht fertig, wenn es einmal funktioniert hat. „Hat funktioniert, als ich's ausprobiert habe" ist der Teststandard von jedem kaputten Skill, den wir je durchfallen ließen. Hier die Mindest-Testreihe, sie deckt sich eng mit dem, was unsere Methodologie bei Einreichungen ausführt:

1. Frische Session. Claude Code komplett neu starten. Skills laden zum Sessionstart; das Testen in der Session, in der du geschrieben hast, beweist nichts.
2. Trigger-Test, positiv. Probier drei verschiedene Formulierungen, die ein echter Nutzer tippen würde: „review this PR", „can you check this diff before I merge", „look over my changes". Alle drei sollten den Skill aktivieren. Du erkennst, ob er gezündet hat, am Output (eine gedeckelte, nach Schweregrad sortierte Findings-Liste sieht anders aus als ein Standard-Review). Im Zweifel frag Claude direkt, ob es den Skill benutzt hat.
3. Trigger-Test, negativ. Probier drei benachbarte Anfragen, die NICHT zünden sollten: „fix this bug", „write a function that parses dates", „why is this test failing?". Wenn deine Review-Checkliste in einer Debugging-Session auftaucht, braucht deine Beschreibung eine „NICHT verwenden"-Klausel.
4. Baseline-Vergleich. Lass denselben Review-Prompt in einer Session mit Skill und einer ohne laufen. Wenn du die Outputs nicht unterscheiden kannst, verdient sich der Skill seinen Kontext nicht, und du solltest die Einschränkungen schärfen. Das ist unser liebster Test, weil er gnadenlos ist. Etwa ein Drittel der Skills, die wir reviewen, scheitert daran.
5. Clean-Install-Test. Falls du veröffentlichen willst: Kopier den Ordner auf eine andere Maschine (oder lösch und klon neu), folge deinem eigenen README wortwörtlich, und schau, ob es funktioniert. Fehlende Abhängigkeits-Hinweise sterben hier.

Die ganze Testreihe dauert 30 Minuten. Sie filtert etwa 80 % der Fehler heraus, die wir sehen – eine starke Rendite für eine halbe Stunde.

Schritt 6: durch den Validator laufen lassen

Bevor du veröffentlichst, wirf deine SKILL.md in unseren kostenlosen Skill-Validator. Er bewertet nach demselben Rubrik, das wir bei Reviews nutzen: Länge und Konkretheit der Beschreibung, Vorhandensein konkreter Trigger-Formulierungen, Negativraum-Klauseln, Einschränkungsdichte im Body, Format-Vorgaben, offensichtliche Anti-Muster wie „powerful" und „anything related to".

Es ist statische Analyse, behandle es entsprechend. Er findet die Fehler, die im Text sichtbar sind, was nach unserer Erfahrung die meisten sind, aber er kann deinen Skill nicht gegen echte Live-Prompts laufen lassen. Ein bestandener Validator-Check plus die Testreihe aus Schritt 5 ist die echte Hürde. Ein bestandener Validator-Check allein ist ein gelinteter Skill, der trotzdem nicht zünden könnte.

Wenn du lieber interaktive Hilfe statt eines Checkers willst: Anthropics Skill Creator ist das Tool, das wir empfehlen. Er erreichte 9,6 in unseren Tests, baut den Ordner auf, und sein Beschreibungs-Optimierungsschritt hat das Triggern bei unseren eigenen internen Skills messbar verbessert. Einen Skill zu benutzen, um Skills zu schreiben, klingt wie ein Witz und funktioniert trotzdem.

Schritt 7: veröffentlichen und einreichen

Veröffentlichung ist ein ganz normales GitHub-Repo. Übliche Struktur:

your-repo/
  README.md           ← was es tut, Installationsbefehl, ein Beispiel
  review-checklist/
    SKILL.md
    reference/

Setz den Installationsbefehl als Copy-Paste-Block ins README, üblich ist das Muster git clone plus cp -r review-checklist ~/.claude/skills/. Füg dann den Topic-Tag claude-skills zum Repo hinzu. Das ist keine Deko: Der Topic-Tag ist, wie unser Crawler und jedes andere Verzeichnis neue Skills entdecken. Ein untagged Skill-Repo ist in der Praxis unsichtbar.

Ein README, das sich zu schreiben lohnt, hat vier Dinge: einen Satz zu dem, was der Skill tut, den Installationsblock, ein Vorher-Nachher-Beispiel und alle Abhängigkeiten. Das Vorher-Nachher-Beispiel bringt mehr für die Akzeptanz als alles andere zusammen, weil es der einzige Teil ist, der zeigt statt behauptet.

Dann bei SkillProof einreichen. Testen und Listen sind kostenlos. Wir lassen die Einreichung durch denselben Prozess laufen wie alles andere im Katalog: frische Installation aus deinem README, Trigger-Testreihe, Baseline-Vergleich, Output-Bewertung. Besteht er, wird er mit einem Score gelistet, und du kannst ein „SkillProof tested"-Badge in dein README einbetten. Für einen unbekannten Autor mit einem zwei Tage alten Repo ist ein unabhängiges Testurteil der Unterschied zwischen „irgendeine SKILL.md aus dem Internet" und etwas, das ein Fremder tatsächlich installiert. Besteht er nicht, bekommst du die Fehlernotizen, fixt sie, und reichst neu ein. Etliche gelistete Skills sind durch zwei Runden gegangen.

Häufige Fehler, die wir in Einreichungen sehen

Nach ein paar hundert Reviews tauchen immer dieselben fünf auf.

Vage Beschreibungen. Mit weitem Abstand immer noch auf Platz eins. Wenn deine Beschreibung drei andere Skills beschreiben könnte, beschreibt sie keinen davon.

Der Alles-in-einem-Skill. Eine SKILL.md, die Reviews, Commits, Refactors und Dokumentation zugleich behandelt. Jeder Job verwässert den Trigger für die anderen. Trenn es.

Modell-Standards nachbeten. Ein Body, der sagt „sei klar, sei genau, denk Schritt für Schritt" bringt nichts. Das macht Claude sowieso. Wenn eine Zeile den Output nicht ändern würde, streich sie.

Keine negativen Einschränkungen. Skills, die nur sagen, was zu tun ist, nie, was zu unterlassen ist. Die „do NOT"-Zeilen sind der Ort, an dem der meiste Verhaltenswechsel passiert.

Ungetestete Installationsanweisungen. Das README sagt, kopier einen Ordner; der Skill hängt still an einem zweiten Skill oder einem Python-Paket. Stirbt jedes Mal an unserem Clean-Install-Schritt, und ist der vermeidbarste Fehler auf dieser Liste.

FAQ

Muss ich programmieren können, um einen Claude Skill zu erstellen? Nein. Eine SKILL.md ist Markdown mit einem YAML-Header. Wenn dein Skill Helfer-Skripte mitliefert, musst du die schreiben, aber reine Anweisungs-Skills, also die meisten, sind einfaches Schreiben. Der Skill in diesem Beitrag enthält null Code.

Wie lang sollte eine SKILL.md sein? So kurz wie möglich, während sie noch Verhalten einschränkt, typischerweise 30 bis 150 Zeilen. Unter etwa 20 Zeilen fügt sie meist nichts über den Standard hinaus hinzu; über ein paar hundert solltest du Details in reference/-Dateien auslagern. Länge ist eine Kosten pro Aktivierung, kein Qualitätssignal.

Warum triggert mein Skill nicht? Fast immer die Beschreibung. Prüfe, ob sie Formulierungen nennt, die ein Nutzer tatsächlich tippen würde, statt Vorteile zu beschreiben, und bestätige, dass du die Session nach der Installation neu gestartet hast, da Skills zum Sessionstart laden. Zündet er bei manchen Formulierungen und bei anderen nicht, füg die fehlenden explizit zur Beschreibung hinzu.

Was ist der Unterschied zwischen einem Skill und einem MCP-Server? Ein Skill ist Anweisung: Markdown, das formt, wie Claude sich verhält, kein Code läuft irgendwo. Ein MCP-Server ist ein Programm, das Claude neue Fähigkeiten gibt, wie den Zugriff auf deine Datenbank. Wenn deine Idee ist „Claude soll X anders angehen", ist es ein Skill. Wenn es „Claude braucht Zugriff auf Y" ist, ist es MCP. Ausführlicher in Claude Skills vs. MCP.

Kann ich Geld für einen Claude Skill verlangen? Es gibt keinen eingebauten Zahlungsmechanismus; Skills sind Dateien, und das öffentliche Ökosystem läuft auf offenen Repos. Manche Autoren verkaufen private Skill-Pakete an Teams als Consulting-Leistung, was funktioniert, weil der Wert das codierte Fachwissen ist, nicht die Datei. Alles, was für den öffentlichen Katalog gedacht ist, sollte offen lizenziert sein, denn niemand installiert einen Skill, den er nicht lesen kann.

Ein Job zuschneiden, den Trigger wie eine Regex in Prosa schreiben, einschränken statt inspirieren, und in einer frischen Session testen, bevor du irgendwem davon erzählst. Das ist das ganze Handwerk. Der Rest ist Iteration, und die Einreichungs-Warteschlange ist offen.