Custom Skills erstellen

Skills (Agent Skills) sind wiederverwendbare Fähigkeiten, die du Claude Code als Verzeichnis mit einer SKILL.md-Datei beibringst. Statt jedes Mal den gleichen Prompt zu formulieren, beschreibst du einmal in der SKILL.md, was der Skill kann – und Claude lädt ihn automatisch, sobald eine Aufgabe dazu passt. Dieser Guide zeigt dir, wie du eigene Skills erstellst und effektiv einsetzt.

Agent Skills sind kein reines Entwickler-Werkzeug: Auch in den Claude-Apps (claude.ai im Browser und Desktop) sowie in Projects kannst du Skills aktivieren und nutzen – dort verwaltest du sie über die Einstellungen statt als Datei im Terminal. Das Konzept ist identisch: Claude lädt einen Skill automatisch, sobald eine Aufgabe zur description passt. Unterschiedlich ist nur, wie du den Skill anlegst. Dieser Guide zeigt den dateibasierten Weg über Claude Code (SKILL.md) – die mächtigste Variante, ideal für versionierbare Team-Workflows.

Für wen ist das?

Für Entwickler, die Claude Code regelmäßig nutzen und merken, dass sie bestimmte Aufgaben immer wieder auf die gleiche Weise erledigen. Skills standardisieren diese Workflows und sparen dir Tipparbeit.

Was lernst du?

Was Agent Skills sind und wie die Auto-Invocation funktioniert
Wo Skill-Verzeichnisse abgelegt werden
Wie du Schritt für Schritt einen eigenen Skill mit SKILL.md erstellst
Drei praktische Beispiele für den Alltag
Wie Progressive Disclosure und Supporting Files funktionieren
Den Unterschied zwischen Skills, Slash-Commands und Hooks

Wann nutzen?

Du führst die gleiche Art von Aufgabe regelmäßig aus (Code Review, Commit Messages, Dokumentation)
Du willst sicherstellen, dass eine Aufgabe immer nach dem gleichen Schema abläuft
Dein Team soll einheitliche Workflows nutzen

Wann nicht?

Für einmalige Aufgaben – da ist ein direkter Prompt schneller
Wenn die Aufgabe jedes Mal komplett anders aussieht und sich nicht standardisieren lässt

Was sind Skills?

Ein Agent Skill ist ein Verzeichnis mit einer Datei namens SKILL.md. Diese Datei hat zwei Teile: ein YAML-Frontmatter mit Metadaten und einen Markdown-Teil mit den eigentlichen Anweisungen.

---
name: commit-messages
description: Erstellt Conventional-Commit-Nachrichten aus den aktuellen Git-Änderungen. Nutze diesen Skill, wenn ein Commit erstellt werden soll.
---

Analysiere alle aktuellen Änderungen (git diff --staged und unstaged)
und erstelle einen Commit mit einer Conventional Commit Message ...

Das Frontmatter braucht mindestens zwei Felder:

name – Kleinbuchstaben, Ziffern und Bindestriche, maximal 64 Zeichen
description – eine prägnante Beschreibung, wann der Skill genutzt werden soll (maximal 1024 Zeichen)

Der entscheidende Punkt: Du rufst einen Skill nicht manuell auf. Claude lädt beim Start nur name und description jedes Skills (rund 100 Token pro Skill) in den Kontext. Sobald eine Aufgabe zur description passt, lädt Claude die vollständige SKILL.md automatisch und befolgt die Anweisungen. Diese Auto-Invocation ist das Herzstück von Agent Skills.

Agent Skills (.claude/skills/<name>/SKILL.md) werden von Claude automatisch geladen, wenn die description zur Aufgabe passt. Slash-Commands (.claude/commands/<name>.md) sind etwas anderes: Sie erzeugen einen Befehl wie /commit, den du manuell eintippst. Beide gibt es weiterhin – aber sie sind nicht dasselbe. Dieser Guide behandelt Agent Skills; Slash-Commands eignen sich, wenn du einen Workflow bewusst per Tastendruck auslösen willst.

Wo Skills abgelegt werden

Jeder Skill bekommt ein eigenes Unterverzeichnis mit einer SKILL.md darin – entweder im Projekt oder global:

Projekt-Skills: .claude/skills/<name>/SKILL.md im Projektverzeichnis – nur für dieses Projekt verfügbar, können ins Repository committed werden
Globale Skills: ~/.claude/skills/<name>/SKILL.md im Home-Verzeichnis – in jedem Projekt verfügbar

.claude/
└── skills/
    └── commit-messages/
        └── SKILL.md

Projekt-Skills werden von allen Teammitgliedern geteilt, wenn sie ins Git-Repository committed werden. Globale Skills sind nur für dich sichtbar.

Projekt-Skills (.claude/skills/) werden ins Repository committed – dein ganzes Team nutzt sie. Globale Skills (~/.claude/skills/) sind nur für dich sichtbar. Faustregel: Alles, was teamweit gelten soll, gehört ins Projekt.

Deinen ersten Skill erstellen

1

Skill-Verzeichnis anlegen

Erstelle das Verzeichnis .claude/skills/<name>/ in deinem Projekt (oder in ~/.claude/skills/<name>/ für globale Skills). Beispiel: .claude/skills/commit-messages/.

Tipp Das Verzeichnis .claude/ existiert möglicherweise schon. Lege darunter skills/<name>/ an – jeder Skill bekommt einen eigenen Ordner.

2

SKILL.md erstellen

Lege in dem Verzeichnis eine Datei SKILL.md an. Sie beginnt mit YAML-Frontmatter (name und description), gefolgt von den Anweisungen als Markdown.

3

description präzise formulieren

Die description entscheidet, wann Claude den Skill lädt. Beschreibe konkret, WAS der Skill tut und WANN er genutzt werden soll – z.B. 'Erstellt Conventional-Commit-Nachrichten. Nutze diesen Skill, wenn ein Commit erstellt werden soll.'

4

Anweisungen schreiben

Schreibe unter dem Frontmatter die eigentlichen Anweisungen als Markdown. Der Inhalt ist das, was Claude befolgt, sobald der Skill geladen wird. Schreibe klar und spezifisch – wie einen guten Prompt.

5

Skill testen

Starte Claude Code und stelle eine Aufgabe, die zur description passt (z.B. 'Erstelle einen Commit'). Prüfe, ob Claude den Skill automatisch lädt und das Ergebnis stimmt. Passe die SKILL.md an, bis es passt.

Drei praktische Beispiele

commit-messages – Bessere Commit Messages

Datei: .claude/skills/commit-messages/SKILL.md

---
name: commit-messages
description: Erstellt Conventional-Commit-Nachrichten aus den aktuellen Git-Änderungen. Nutze diesen Skill, wenn ein Commit erstellt werden soll.
---

Analysiere alle aktuellen Änderungen (git diff --staged und unstaged).

Erstelle einen Commit mit einer Conventional Commit Message:
- Format: type(scope): beschreibung
- Types: feat, fix, refactor, docs, test, chore
- Scope: betroffenes Modul oder Feature
- Beschreibung: kurz, prägnant, auf Englisch

Zeige mir die vorgeschlagene Message, bevor du den Commit erstellst.

Auslöser: „Erstelle einen Commit für meine Änderungen.”

code-review – Code Review Checkliste

Datei: .claude/skills/code-review/SKILL.md

---
name: code-review
description: Führt ein strukturiertes Code Review einer Datei durch. Nutze diesen Skill, wenn Code überprüft oder reviewt werden soll.
---

Führe ein Code Review für die angegebene Datei durch.

Prüfe diese Punkte:
1. **Lesbarkeit:** Sind Variablennamen verständlich? Gibt es unnötige Komplexität?
2. **Fehlerbehandlung:** Werden Fehlerfälle abgefangen? Gibt es fehlende try/catch?
3. **Typen:** Gibt es `any` oder fehlende Typ-Annotationen?
4. **Tests:** Gibt es Tests für die Kernlogik? Fehlen Edge Cases?
5. **Security:** Gibt es hartcodierte Secrets, SQL-Injection-Risiken oder unsanitized Input?

Gib für jeden Punkt eine Bewertung (OK / Verbesserung nötig) und konkrete Vorschläge.

Auslöser: „Review die Datei src/auth/login.ts.”

docstrings – Dokumentation generieren

Datei: .claude/skills/docstrings/SKILL.md

---
name: docstrings
description: Generiert JSDoc-Dokumentation für eine Funktion. Nutze diesen Skill, wenn Code dokumentiert werden soll.
---

Generiere Dokumentation für die angegebene Funktion.

Format:
- Kurzbeschreibung (1-2 Sätze)
- Parameter mit Typen und Beschreibung
- Rückgabewert
- Beispiel-Aufruf
- Mögliche Fehler

Schreibe die Dokumentation als JSDoc-Kommentar direkt in die Datei.
Wenn die Funktion bereits dokumentiert ist, aktualisiere die bestehende
Dokumentation.

Auslöser: „Dokumentiere die Funktion in src/utils/formatDate.ts.”

Progressive Disclosure und Supporting Files

Skills sind so gebaut, dass sie den Kontext schonen. Claude lädt beim Start nur name und description jedes Skills – die vollständige SKILL.md erst, wenn der Skill tatsächlich gebraucht wird. Dieses gestufte Laden heißt Progressive Disclosure.

Für umfangreichere Skills kannst du neben der SKILL.md weitere Dateien im Skill-Verzeichnis ablegen – sogenannte Supporting Files (z.B. Referenzdokumente, Vorlagen oder Skripte). Claude lädt diese nur bei Bedarf nach. So bleibt der Kontext schlank, auch wenn ein Skill viel Wissen mitbringt.

.claude/skills/code-review/
├── SKILL.md
├── checklist.md        ← Supporting File, nur bei Bedarf geladen
└── examples/
    └── good-review.md

✗

description: Hilft beim Programmieren.

✓

description: Führt ein strukturiertes Code Review durch (Lesbarkeit, Fehlerbehandlung, Typen, Tests, Security). Nutze diesen Skill, wenn Code überprüft werden soll.

Die description entscheidet, ob Claude den Skill im richtigen Moment lädt. 'Hilft beim Programmieren' ist zu vage – beschreibe konkret, WAS der Skill tut und WANN er genutzt werden soll.

Skills vs. Slash-Commands vs. Hooks

Diese drei Erweiterungen klingen ähnlich, funktionieren aber unterschiedlich:

Aspekt	Agent Skills	Slash-Commands	Hooks
Auslöser	Automatisch (Claude erkennt die passende Aufgabe)	Manuell (du tippst `/command-name`)	Automatisch (bei bestimmten Events)
Ablage	`.claude/skills/<name>/SKILL.md`	`.claude/commands/<name>.md`	settings.json
Format	YAML-Frontmatter + Markdown-Anweisungen	Markdown mit Prompt	JSON mit Command-Definition
Zweck	Wiederkehrende Fähigkeiten, die Claude selbst einsetzt	Workflows, die du bewusst per Befehl auslöst	Automatische Aktionen bei Events
Beispiel	Commit-Messages erstellen	`/deploy` für ein Deployment	Pre-Commit Hook für Linting

Agent Skills lädt Claude selbst, sobald eine Aufgabe zur description passt. Slash-Commands löst du gezielt per Tastendruck aus. Hooks laufen automatisch im Hintergrund bei bestimmten Events.

Mehr zum Unterschied zwischen Skills und anderen Erweiterungen findest du im Vergleich Skills vs. MCP.

Du willst, dass Claude Code bei jeder Dateiänderung automatisch den Linter ausführt. Was brauchst du?

Typische Fehler

Zu komplexe Skills: Ein Skill, der 500 Wörter lang ist und 10 Dinge gleichzeitig tut, liefert unvorhersehbare Ergebnisse. Halte Skills fokussiert auf eine Aufgabe.
Vage description: Wenn die description nicht klar sagt, WANN der Skill greift, lädt Claude ihn im falschen Moment oder gar nicht. Beschreibe Aufgabe und Auslöser konkret.
CLAUDE.md duplizieren: Wenn eine Regel immer gelten soll, gehört sie in die CLAUDE.md, nicht in einen Skill. Skills sind für abgegrenzte, wiederkehrende Aufgaben.
Skills nicht ins Repository committen: Wenn dein Team den gleichen Skill nutzen soll, committe .claude/skills/ ins Repository.
Alles in die SKILL.md packen: Umfangreiches Referenzwissen gehört in Supporting Files, die Claude nur bei Bedarf nachlädt – so bleibt der Kontext schlank (Progressive Disclosure).

Mini-Übung

Erstelle einen Skill, der Conventional Commit Messages generiert:

Erstelle das Verzeichnis .claude/skills/commit-messages/ in deinem Projekt
Erstelle die Datei .claude/skills/commit-messages/SKILL.md mit YAML-Frontmatter (name, description)
Schreibe unter dem Frontmatter Anweisungen, die Claude anweisen, den Diff zu analysieren und eine Conventional Commit Message zu generieren
Mache eine kleine Änderung an einer Datei
Bitte Claude um einen Commit und prüfe, ob der Skill automatisch geladen und die Message generiert wird
Passe die description und die Anweisungen an, bis die Messages deinem Stil entsprechen

Nächster Schritt

Du kannst jetzt eigene Skills erstellen und wiederkehrende Aufgaben automatisieren. Entdecke weitere Möglichkeiten, Claude Code zu erweitern, unter Mit Claude bauen. Oder lies den Vergleich Skills vs. MCP, um zu verstehen, wann welche Erweiterung die richtige ist.

Glossar Practice Hub Alle Guides

War das hilfreich?

Damit kannst du jetzt: Eigene Agent Skills als SKILL.md mit YAML-Frontmatter erstellen, die Claude über die description automatisch erkennt und lädt.

Nächster Guide Extended Thinking gezielt einsetzen →

Neu → In Arbeit → Verstanden → Praxis

← Vorheriger Guide Git-Workflow mit Claude Code Nächster Guide → Extended Thinking gezielt einsetzen

CLAUDE.md schreiben

Die Konfigurationsdatei für Claude Code – Projektstruktur, Konventionen und Regeln in einer Datei.