SKILL.md erklärt: Aufbau, Beispiele, Best Practices

Eine SKILL.md besteht aus YAML-Frontmatter mit name und description sowie einem Markdown-Körper mit Anweisungen. Die description entscheidet, wann der Agent den Skill lädt — sie ist das wichtigste Feld. Umfangreiches Wissen wandert in referenzierte Zusatzdateien, wiederholbare Abläufe in mitgelieferte Skripte.

Wie ist eine SKILL.md aufgebaut?

Jeder Skill beginnt mit einem YAML-Frontmatter-Block — einem maschinenlesbaren Kopfbereich zwischen zwei ----Zeilen am Dateianfang. Zwei Felder sind Pflicht: name — der Bezeichner in Kleinbuchstaben mit Bindestrichen — und description — der Text, an dem der Agent erkennt, wann der Skill relevant ist. Ein minimales Beispiel:

---
name: commit-messages
description: Schreibt Commit-Messages nach Conventional
  Commits. Verwenden bei git commit, Commit-Texten oder
  Changelog-Erstellung.
---

# Commit Messages

## Format
<type>(<scope>): <beschreibung>

Erlaubte Typen: feat, fix, docs, refactor, test, chore.
Beschreibung im Imperativ, maximal 72 Zeichen, keine
Punkte am Ende.

Nach dem Frontmatter folgt normales Markdown: Regeln, Beispiele, Schritt-für-Schritt-Abläufe. Der Agent liest diesen Körper erst, wenn der Skill tatsächlich ausgelöst wurde — bis dahin kennt er nur name und description. Diese Zweiteilung ist der Kern des Formats: Der Kopf entscheidet über das Wann, der Körper über das Wie.

Warum ist die description so wichtig?

Die description ist der Auslöse-Mechanismus: Der Agent vergleicht jede Aufgabe mit den Beschreibungen aller installierten Skills und lädt die passenden. Eine vage description („Hilft beim Schreiben") führt dazu, dass der Skill nie oder ständig geladen wird — beides macht ihn nutzlos. Gute descriptions nennen konkret, was der Skill tut und wann er greifen soll, inklusive typischer Stichwörter aus Nutzeranfragen.

Anthropics skill-creator — selbst ein Skill — kodifiziert genau diese Formulierungsarbeit und ist der empfohlene Startpunkt für eigene Skills: Er fragt Zweck und Auslöser ab und formuliert daraus eine tragfähige description.

Was gehört in Zusatzdateien und Skripte?

Die Kunst guter Skills heißt Progressive Disclosure, also gestaffeltes Offenlegen von Wissen: Die SKILL.md bleibt kompakt und verweist für Details auf weitere Dateien im Skill-Ordner — etwa eine reference.md mit vollständigen Formatspezifikationen, die der Agent nur bei Bedarf liest. So kostet der Skill im Normalfall kaum Kontext, kann aber beliebig tiefes Wissen transportieren.

Wiederholbare Abläufe gehören in Skripte statt in Prosa: Anthropics pdf-Skill etwa liefert erprobte Python-Werkzeuge mit, statt den Agent bei jedem Formular improvisieren zu lassen. Skripte machen das Verhalten deterministisch — derselbe Ablauf, jedes Mal.

Welche Fehler machen selbstgebaute Skills kaputt?

Drei Muster tauchen immer wieder auf. Erstens: der Alles-Skill — ein einziger Skill für „Backend-Entwicklung" ist zu breit, um zuverlässig ausgelöst zu werden; besser sind fokussierte Skills pro Arbeitsschritt. Zweitens: Roman statt Regelwerk — Agents befolgen knappe, imperative Anweisungen besser als ausschweifende Erklärungen. Drittens: fehlende Praxistests — ob eine description funktioniert, zeigt nur der Versuch in einer frischen Session mit realen Aufgaben.

Wer diese Klippen umschifft, hat ein mächtiges Werkzeug: Team-Wissen, das sich versionieren, teilen und in jedem kompatiblen Agent wiederverwenden lässt.

Wie gehst du beim ersten eigenen Skill vor?

Ein bewährter Ablauf in vier Schritten:

1. Problem wählen: Nimm eine Aufgabe, die du dem Agent in den letzten Wochen mehrfach mit denselben Korrekturen erklärt hast — genau dieses wiederholte Erklären ist das Rohmaterial eines Skills.
2. Minimal starten: Frontmatter plus zehn bis zwanzig Zeilen imperative Regeln. Keine Referenzdateien, keine Skripte — die kommen erst, wenn die Grundversion trägt.
3. In frischer Session testen: Neue Session, realistische Aufgabe, ohne den Skill zu erwähnen. Lädt er? Befolgt der Agent die Regeln? Falls nicht: description schärfen, nicht den Körper aufblähen.
4. Iterieren und teilen: Erst wenn der Skill bei dir zuverlässig greift, lohnt der Feinschliff — und danach das Teilen im Team oder als öffentliches Repository.

Wie du fertige Skills installierst und organisierst, zeigt Skills in Claude Code installieren.