Claude Code Skills erstellen und installieren: SKILL.md-Vorlage auf Deutsch

Du erklärst Claude Code jede Woche dieselbe Checkliste? Dann gehört sie in einen Skill. Ein Skill ist ein Ordner mit einer SKILL.md-Datei. Claude lädt ihn, wenn er zur Aufgabe passt, oder wenn du /skill-name tippst.

Hier lernst du, wie du Skills installierst, einen eigenen Skill erstellst und typische Fehler behebst.

Was sind Claude Code Skills?

Ein Skill ist eine Anleitung, die Claude bei Bedarf nachlädt. Laut Claude-Code-Doku lohnt sich ein Skill, wenn du immer wieder dieselben Anweisungen, Checklisten oder mehrstufigen Abläufe in den Chat kopierst.

Der Unterschied zur CLAUDE.md: Der Inhalt eines Skills wird erst geladen, wenn er gebraucht wird. In der Skill-Liste steht nur die Beschreibung. Lange Referenztexte kosten also kaum Kontext, bis du sie brauchst.

Dauerhafte Projektregeln legst du in der CLAUDE.md ab: CLAUDE.md-Vorlage.

Claude Code Skills folgen dem offenen Standard Agent Skills. Claude Code erweitert ihn um eigene Felder, zum Beispiel für die Steuerung, wer einen Skill aufrufen darf.

Übrigens: Eigene Befehle unter .claude/commands/deploy.md funktionieren weiter. Ein Skill unter .claude/skills/deploy/SKILL.md erzeugt denselben Befehl /deploy, kann aber zusätzlich eigene Dateien mitbringen.

Skills installieren

Ordner anlegen (persönlich vs. Projekt)

Wo der Skill liegt, entscheidet, wo er geladen wird:

# persönlich
mkdir -p ~/.claude/skills/commit-nachricht

# nur für dieses Projekt
mkdir -p .claude/skills/commit-nachricht

Gibt es denselben Namen persönlich und im Projekt, gewinnt der persönliche Skill.

Zwei Ordnernamen sind reserviert: synced und anthropic-skills. Nimm sie nicht für eigene Skills.

Skills aus GitHub übernehmen: Quelle prüfen, Skripte lesen

Viele suchen nach „claude code skills download“ oder „claude code skills github“. Beispiel-Skills von Anthropic findest du unter github.com/anthropics/skills. Installieren heißt hier: den Skill-Ordner in einen der beiden Pfade oben kopieren.

Bevor du einen fremden Skill übernimmst:

• Lies die SKILL.md komplett. Achte auf Zeilen, die mit ! beginnen. Damit führt Claude Code Shell-Befehle aus, bevor Claude den Skill überhaupt sieht.
• Prüfe allowed-tools im Frontmatter. Dort stehen Tools, die Claude ohne Rückfrage nutzen darf, solange der Skill läuft. Laut Doku gilt das auch für Projekt-Skills in Ordnern, denen du nie vertraut hast. Schau dir das also vorher an.
• Lies die Skripte im Ordner (scripts/ o. ä.), bevor Claude sie ausführt.

Prüfen, ob Claude den Skill erkennt

Claude Code beobachtet die Skill-Ordner. Neue oder geänderte Skills unter ~/.claude/skills/ oder .claude/skills/ werden in der laufenden Session übernommen, ohne Neustart. Hast du den obersten Skills-Ordner erst während der Session angelegt, führe /reload-skills aus.

Dann frag: „What skills are available?“ oder öffne /skills. Taucht dein Skill auf, ist er installiert.

Eigenen Skill erstellen: SKILL.md Schritt für Schritt

Frontmatter (name, description)

Die SKILL.md beginnt mit YAML-Frontmatter zwischen zwei ---. Das erste --- muss in der ersten Zeile stehen. Sonst behandelt Claude Code die ganze Datei als normalen Inhalt.

Die Agent-Skills-Spezifikation verlangt zwei Felder:

• name: 1–64 Zeichen, nur Kleinbuchstaben, Ziffern und Bindestriche. Kein Bindestrich am Anfang oder Ende, kein --. Muss zum Ordnernamen passen.
• description: 1–1.024 Zeichen. Beschreibt, was der Skill tut und wann er greifen soll.

Claude Code selbst ist großzügiger: Alle Felder sind optional, empfohlen ist nur description. Fehlt name, nimmt Claude Code den Ordnernamen. Wenn du den Skill später auf claude.ai hochladen willst, bleib bei den Feldern der Spezifikation (siehe FAQ).

Anweisungen und Beispiele

Nach dem Frontmatter folgt normales Markdown. Die Spezifikation empfiehlt Schritt-für-Schritt-Anweisungen, Beispiele für Ein- und Ausgaben und Sonderfälle.

Halte die Datei knapp. Ist ein Skill einmal geladen, bleibt sein Inhalt über mehrere Antworten im Kontext. Jede Zeile kostet also immer wieder Tokens. Die Doku empfiehlt, SKILL.md unter 500 Zeilen zu halten und Details in eigene Dateien auszulagern.

Beschreibung zweisprachig formulieren (EN + DE-Trigger)

Die description entscheidet, ob Claude den Skill von selbst lädt. Schreib die Wörter hinein, die du tatsächlich tippst, und zwar in beiden Sprachen, wenn du gemischt arbeitest:

description: Writes a Conventional Commits message for staged changes. Use when the user asks for a commit message, Commit-Nachricht or Commit-Text.

Stell den wichtigsten Anwendungsfall an den Anfang. Claude Code kürzt description plus when_to_use in der Skill-Liste auf 1.536 Zeichen.

SKILL.md-Beispiel (deutsch kommentiert)

Speichern unter .claude/skills/commit-nachricht/SKILL.md. Die Kommentare im Frontmatter (#) sind gültiges YAML.

---
# Muss zum Ordnernamen passen: commit-nachricht
name: commit-nachricht
# Was der Skill tut + wann er greifen soll, mit EN- und DE-Triggern
description: Schreibt eine Commit-Nachricht nach Conventional Commits für die gestagten Änderungen. Use when the user asks for a commit message, Commit-Nachricht or wants to commit.
---

# Commit-Nachricht

## Schritte
1. Führe `git diff --staged` aus und lies die Änderungen.
2. Wähle genau einen Typ: feat, fix, docs, refactor, test, chore.
3. Betreffzeile unter 72 Zeichen, im Imperativ.
4. Text darunter nur, wenn die Änderung Kontext braucht.

## Ausgabe
- Die Nachricht in einem Codeblock.
- Nicht selbst committen.

Testen: Frag „Schreib mir eine Commit-Nachricht“ oder tipp direkt /commit-nachricht.

Soll Claude einen Skill nie von selbst starten (etwa ein Deployment), ergänze disable-model-invocation: true. Das ist ein Claude-Code-Feld, kein Feld der Spezifikation.

Skills, die Shell-Befehle ausführen: was Claude Code fragt

Ein Skill kann mit ` !befehl ` die Ausgabe eines Shell-Befehls einfügen, bevor Claude den Text sieht. Für diese eingebetteten Befehle gilt laut Doku:

• Sie fragen nicht nach, während der Skill geladen wird. Claude Code prüft sie gegen deine Berechtigungsregeln.
• Passt eine Deny-Regel, bricht der Skill-Aufruf ab.
• Außerhalb des Auto-Modus bricht der Aufruf auch ab, wenn die Prüfung nicht „erlaubt“ ergibt. Willst du das vermeiden, gib den Befehl gezielt über allowed-tools frei.
• Mit "disableSkillShellExecution": true in den Einstellungen werden solche Befehle für eigene, Projekt- und Plugin-Skills nicht ausgeführt.

Für Tools, die Claude während des Skills nutzt, gilt allowed-tools: Die Freigabe gilt nur für den Zug, in dem der Skill aufgerufen wurde, und endet mit deiner nächsten Nachricht.

Fehlerbehebung

• „SKILL.md must start with YAML frontmatter (---)“: Über dem ersten --- steht etwas. Entfernen.
• Skill lädt, greift aber nie: Wahrscheinlich ist das YAML kaputt. Dann lädt Claude Code den Skill ohne Felder, /skill-name geht noch, aber die Beschreibung wird nicht gefunden. Starte claude --debug, um den Parse-Fehler zu sehen, oder prüfe den Ordner mit claude plugin validate .claude/skills.
• Frontmatter-Fehler finden: Ab Claude Code v2.1.233 meldet claude plugin validate .claude/skills (bzw. ~/.claude/skills) SKILL.md-Dateien, deren Frontmatter sich nicht parsen lässt.
• Skill fehlt im /-Menü: Prüfe den Namen auf Sonderzeichen wie ein Zero-Width-Space, < oder >, ein geschütztes Leerzeichen oder zwei Leerzeichen hintereinander. Welchen Namen Claude Code abgelehnt hat, siehst du, wenn du claude --debug startest und im Debug-Log nach [names] suchst.
• Skill greift zu oft: Beschreibung enger fassen oder disable-model-invocation: true setzen.

Lieber mit fertigen Skills starten?

Keine Lust, bei null anzufangen? Das Claude Code Skills Pack von Aramac: 14 Skills, validiert gegen die Agent-Skills-Spezifikation (claude plugin validate, Claude Code 2.1.301). Nur für eigene, nicht gewerbliche Zwecke (Lizenz). 29 € inkl. MwSt., Updates bis 16.04.2027.

Passende Vorlagen für AGENTS.md und CLAUDE.md gibt es separat im Cursor + Claude Code Rules Pack (19 € inkl. MwSt.).

FAQ

Wo speichere ich einen Claude Code Skill?
In einem Ordner, der wie der Skill heißt: ~/.claude/skills/<name>/SKILL.md für alle deine Projekte oder .claude/skills/<name>/SKILL.md nur für ein Projekt.

Welche Felder braucht die SKILL.md?
Die Agent-Skills-Spezifikation verlangt name und description. In Claude Code sind alle Felder optional, empfohlen ist description; fehlt name, gilt der Ordnername.

Muss ich Claude Code nach dem Installieren neu starten?
Meist nicht. Claude Code übernimmt Änderungen in bestehenden Skill-Ordnern in der laufenden Session. Hast du den obersten Skills-Ordner erst während der Session angelegt, führe /reload-skills aus.

Warum wird mein Skill nicht geladen?
Prüfe, ob das erste --- in Zeile 1 steht, ob das YAML gültig ist und ob die Beschreibung die Wörter enthält, die du benutzt. Mit claude --debug siehst du Parse-Fehler.

Funktionieren meine Skills auch auf claude.ai?
Du kannst sie dort hochladen. Erlaubt sind dann nur die sechs Felder der Spezifikation: name, description, license, compatibility, metadata und allowed-tools. Andere Felder führen zu einem Fehler beim Hochladen.

Quellen

• Anthropic, Claude Code Doku: Extend Claude with skills (deutsche Fassung: code.claude.com/docs/de/skills)
• Agent Skills: Specification
• Offizielle Beispiel-Skills: github.com/anthropics/skills

Alle geprüft am 16. Oktober 2026.

---

Ein unabhängiges Produkt der Aramac GmbH. Nicht mit Anysphere (Cursor) oder Anthropic (Claude Code) verbunden oder von ihnen unterstützt. Cursor und Claude sind Marken ihrer jeweiligen Inhaber.