Claude Code Skills: was sie sind und wie du einen baust

Ein Skill in Claude Code ist ein Ordner mit einer Datei namens SKILL.md. Oben stehen Name und Beschreibung, darunter die Anleitung, der Claude folgen soll. Claude kennt anfangs nur die Beschreibung und lädt den Rest erst, wenn deine Anfrage dazu passt oder du /skill-name tippst. So bleibt der Kontext schlank.

Alles hier stützt sich auf die Skills-Seite der Claude-Code-Doku und auf Anthropics Übersicht zu Agent Skills. Beide Seiten sind Stand 7. November 2026. Claude Code ändert sich schnell, prüf Details deshalb vor dem Ausrollen in der aktuellen Doku.

Was steht in einer SKILL.md?

Die Datei hat zwei Teile. Zwischen zwei ----Zeilen steht YAML-Frontmatter, danach folgt normales Markdown mit den Anweisungen. Laut Doku ist jedes Feld im Frontmatter optional. Empfohlen wird nur description, denn daran entscheidet Claude, wann der Skill gebraucht wird.

Der Befehl, den du tippst, kommt aus dem Ordnernamen oder aus dem Feld name. Ein Skill unter .claude/skills/changelog-eintrag/SKILL.md heißt also /changelog-eintrag. Namen bestehen laut Anthropic aus Kleinbuchstaben, Ziffern und Bindestrichen und haben höchstens 64 Zeichen.

Ein kleines Beispiel für ein Team, das Changelog-Einträge immer im gleichen Format haben will:

---
name: changelog-eintrag
description: Schreibt einen Changelog-Eintrag im Format des Teams. Verwenden, wenn jemand einen Changelog-Eintrag, Release Notes oder eine Zusammenfassung der Änderungen für Kunden will.
---

## Aktuelle Änderungen

!`git diff HEAD --stat`

## Anleitung

1. Fasse die Änderungen oben in höchstens fünf Stichpunkten zusammen.
2. Schreib aus Sicht der Nutzer, ohne Dateinamen.
3. Sortiere nach „Neu“, „Verbessert“ und „Behoben“.
4. Zeig den Entwurf zur Freigabe, bevor du CHANGELOG.md änderst.

Die Zeile mit dem Ausrufezeichen ist eine Funktion von Claude Code. Laut Doku führt Claude Code den Befehl aus, bevor Claude den Skill liest, und setzt die Ausgabe an dieser Stelle ein. Claude bekommt also den echten Stand deines Repos und muss nicht raten.

Die Beschreibung trägt die meiste Last. Schreib hinein, was der Skill tut und bei welchen Formulierungen er greifen soll. Beschreibung und das optionale Feld when_to_use werden in der Skill-Liste zusammen nach 1.536 Zeichen abgeschnitten, das Wichtigste gehört also nach vorn.

Wie findet Claude einen Skill?

Anthropic nennt das Prinzip „progressive disclosure“, also Laden in Stufen. Zum Start einer Sitzung landen nur Name und Beschreibung jedes Skills im Kontext. Die Übersicht zu Agent Skills rechnet mit rund 100 Tokens pro Skill. Den eigentlichen Text der SKILL.md holt Claude erst, wenn du ihn per Slash-Befehl aufrufst oder Claude deine Anfrage der Beschreibung zuordnet.

Einmal geladen, bleibt der Inhalt als eine Nachricht in der Unterhaltung. Die Doku sagt ausdrücklich, dass Claude Code die Datei in späteren Runden nicht erneut liest. Anweisungen, die für die ganze Aufgabe gelten sollen, formulierst du deshalb als Dauerregel („Führ nach jeder Änderung die Tests aus“). Ein einmaliger Schritt reicht dafür nicht.

Weitere Dateien im Skill-Ordner kosten nichts, solange niemand sie braucht. Eine reference.md mit API-Details liest Claude nur bei Bedarf. Bei Skripten kommt laut Anthropic nur die Ausgabe in den Kontext, der Code selbst nicht. Die Doku empfiehlt, die SKILL.md unter 500 Zeilen zu halten und Details auszulagern.

Zwei Felder ändern diesen Ablauf. Mit disable-model-invocation: true steht die Beschreibung gar nicht im Kontext, und der Skill läuft nur, wenn du ihn selbst aufrufst. Die Doku empfiehlt das für alles mit Nebenwirkungen, etwa Deployments oder Commits. Mit user-invocable: false verschwindet der Skill aus dem /-Menü, Claude kann ihn aber weiter nutzen. Das passt für Hintergrundwissen, zum Beispiel wie ein altes System funktioniert.

Wo liegen Skills, und wer bekommt sie?

Der Speicherort entscheidet, in welchen Sitzungen ein Skill auftaucht. Die Doku nennt diese Ebenen:

Gibt es denselben Namen mehrfach, gewinnt Enterprise vor persönlich und persönlich vor Projekt. In einem Monorepo lädt Claude Code Projekt-Skills aus dem Startordner und aus jedem übergeordneten Ordner bis zur Wurzel des Repos. Skills in tieferen Unterordnern kommen erst dazu, wenn Claude dort eine Datei liest oder bearbeitet. Änderungen an einer SKILL.md übernimmt Claude Code laut Doku in der laufenden Sitzung, ohne Neustart.

Skill, CLAUDE.md, Slash-Befehl oder Subagent?

Die vier Begriffe liegen nah beieinander. Die Tabelle fasst zusammen, was die Doku zu jedem sagt:

Für die Abgrenzung zu CLAUDE.md gibt die Doku zu CLAUDE.md eine klare Regel. Dort gehört hinein, was Claude in jeder Sitzung wissen muss. Ist ein Eintrag ein mehrstufiger Ablauf oder betrifft er nur einen Teil des Codes, gehört er in einen Skill.

Eigene Slash-Befehle sind inzwischen in Skills aufgegangen. Eine Datei .claude/commands/deploy.md und ein Skill unter .claude/skills/deploy/SKILL.md erzeugen beide /deploy. Für neue Arbeit empfiehlt die Doku Skills, weil sie Zusatzdateien und die Steuerung per Frontmatter mitbringen.

Subagenten laufen in einem eigenen Kontextfenster, mit eigenem System-Prompt und eigenen Werkzeugrechten. Beides lässt sich kombinieren. Setzt du in einem Skill context: fork, startet Claude Code einen Subagenten und gibt ihm den Skill-Text als Auftrag. Dieser Subagent sieht deinen bisherigen Gesprächsverlauf nicht. Umgekehrt kann ein Subagent Skills als Wissen vorab laden.

Einen Skill in fünf Schritten anlegen

1. Leg einen Ordner an, persönlich unter ~/.claude/skills/changelog-eintrag/ oder fürs Team im Repo unter .claude/skills/changelog-eintrag/.
2. Schreib darin eine SKILL.md mit Frontmatter und Anleitung, wie im Beispiel oben.
3. Formulier die description so, wie Leute im Team tatsächlich fragen würden. Fehlen diese Wörter, greift der Skill oft nicht. Die Doku nennt die Beschreibung als ersten Prüfpunkt bei der Fehlersuche.
4. Teste beide Wege in einer frischen Sitzung. Frag einmal frei („Schreib mir einen Changelog-Eintrag“) und ruf ihn einmal direkt mit /changelog-eintrag auf.
5. Committe den Ordner, wenn es ein Projekt-Skill ist. Ab dann hat ihn jeder, der das Repo auscheckt.

Greift der Skill zu oft, machst du die Beschreibung enger oder setzt disable-model-invocation: true. Ist das YAML im Frontmatter kaputt, lädt Claude Code den Skill laut Doku trotzdem, nur ohne Metadaten. Dann funktioniert /name noch, das automatische Erkennen über die Beschreibung aber nicht.

Wann lohnen sich Skills für ein Team?

Die Doku nennt einen einfachen Anlass. Du kopierst immer wieder dieselbe Anleitung, Checkliste oder Schrittfolge in den Chat. Oder ein Abschnitt in der CLAUDE.md ist zu einem Ablauf gewachsen. Für Teams kommt dazu, dass ein committeter Skill bei allen gleich läuft. Code-Review-Kriterien, das Format für Release Notes oder die Schritte für ein Deployment stehen dann einmal im Repo und nicht in fünf privaten Prompt-Sammlungen.

Für Firmen gibt es drei Wege zum Verteilen. Projekt-Skills kommen über Git. Plugins bringen Skills in einem eigenen skills/-Ordner mit, und Managed Settings verteilen sie an alle Rechner der Organisation. Skills folgen außerdem dem offenen Standard Agent Skills. Laut Doku lassen sich Skills mit den Standardfeldern auch außerhalb von Claude Code nutzen, Funktionen wie die eingebettete Befehlszeile dagegen nur in Claude Code.

Ein Punkt gehört in jede Einführung. Anthropic rät, Skills nur aus vertrauenswürdigen Quellen zu nutzen, also selbst geschriebene oder solche von Anthropic. Ein Skill bringt Anweisungen und oft auch Code mit. Ein bösartiger Skill kann Claude dazu bringen, Werkzeuge anders zu nutzen, als die Beschreibung verspricht. Fremde Skills sollte jemand vor dem Einsatz komplett durchlesen, Skripte eingeschlossen.

Meine Meinung dazu: Fang mit zwei oder drei Skills für Abläufe an, über die sich das Team heute schon ärgert. Ein kurzer Skill, den alle nutzen, bringt mehr als zwanzig, die niemand kennt. Warum eine lange CLAUDE.md Tokens kostet und Skills da sparsamer sind, steht im Artikel zum Claude-Code-Preis. Falls ihr noch zwischen Werkzeugen schwankt, hilft der Überblick zu Alternativen zu Claude Code.

Du willst Skills, CLAUDE.md und Subagenten für dein Team sauber aufsetzen? Schreib mir, dann schauen wir gemeinsam drauf. Mehr über mich steht auf der Über-mich-Seite.