Claude Code Skills: Aufbau, SKILL.md und wann sich ein Skill lohnt
Claude Code Skills erklärt: Aufbau der SKILL.md, Speicherorte, Frontmatter-Felder, Unterschied zu Commands, Hooks und Subagenten, plus ein Beispiel-Skill fürs Team.
Veröffentlicht: 2026-09-23. Aktualisiert: 2026-09-23.
Das Wichtigste in Kürze
- Ein Skill ist ein Ordner mit einer SKILL.md: Anweisungen, die Claude Code bei Bedarf lädt oder die Sie mit /skill-name aufrufen.
- Der Inhalt eines Skills wird erst beim Einsatz geladen. Das hält den Kontext klein und senkt die Kosten gegenüber einer langen CLAUDE.md.
- Commands sind in Skills aufgegangen: .claude/commands/deploy.md und .claude/skills/deploy/SKILL.md erzeugen beide /deploy.
- Die description entscheidet, ob Claude einen Skill von selbst nutzt. Sie ist das wichtigste Feld.
- Skills sind Anweisungen, keine Garantie. Was immer passieren muss, gehört in einen Hook.
Ein Claude Code Skill ist ein Ordner mit einer Datei SKILL.md, die Claude Code eine wiederkehrende Aufgabe beibringt: ein Review nach Teamregeln, einen Release-Ablauf, die Konventionen eines Frameworks. Claude lädt den Skill, wenn die Beschreibung zur Aufgabe passt, oder Sie rufen ihn mit /skill-name auf. Weil der Inhalt erst beim Einsatz geladen wird, bleibt der Kontext klein. Dieser Artikel zeigt Aufbau, Speicherorte, die wichtigsten Felder und die Abgrenzung zu Hooks und Subagenten.
Stand: 23. September 2026, auf Basis der offiziellen Claude-Code-Dokumentation (Quellen am Ende).
Was ist ein Skill in Claude Code?
Ein Skill bündelt Anweisungen für eine Aufgabe. Claude Code kennt von jedem Skill zunächst nur Name und Beschreibung. Erst wenn eine Anfrage dazu passt oder Sie den Skill aufrufen, wird der Inhalt geladen. Das ist der Unterschied zur CLAUDE.md, die in jeder Sitzung vollständig im Kontext steht.
Skills folgen dem offenen Standard Agent Skills. Derselbe Aufbau funktioniert deshalb auch in anderen Agenten, die den Standard unterstützen, etwa in Hermes Agent.
Wo liegen Skills?
| Ebene | Pfad | Gilt für |
|---|---|---|
| Persönlich | ~/.claude/skills/<name>/SKILL.md | alle Ihre Projekte |
| Projekt | .claude/skills/<name>/SKILL.md | alle, die das Repository nutzen |
| Plugin | <plugin>/skills/<name>/SKILL.md | Aufruf als /plugin-name:skill-name |
| Unternehmen | verwaltete Einstellungen | zentral verteilt |
Projekt-Skills gehören ins Repository und werden wie Code reviewt. Persönliche Vorlieben bleiben im Home-Verzeichnis. Wie sich das in den übrigen .claude-Ordner einfügt, zeigt mein Artikel Der .claude-Ordner in Claude Code erklärt.
Wie ist eine SKILL.md aufgebaut?
Eine SKILL.md besteht aus YAML-Frontmatter und Markdown-Anweisungen. Ein Beispiel für ein Team-Review:
---
name: team-review
description: Prüft einen Diff nach den Review-Regeln dieses Repos. Nutzen, wenn der Nutzer ein Review, eine PR-Prüfung oder "schau über den Diff" anfragt.
allowed-tools: Bash(git diff:*), Bash(npm run lint), Read, Grep
---
# Team-Review
1. `git diff origin/main...HEAD` lesen.
2. Jede geänderte Datei gegen `review-regeln.md` in diesem Ordner prüfen.
3. Befunde nach Schwere sortieren: Fehler, Risiko, Stil.
4. Keine Änderungen vornehmen, nur berichten.
Die Ordnerstruktur dazu:
.claude/skills/team-review/
├── SKILL.md
├── review-regeln.md # Referenz, wird bei Bedarf gelesen
└── scripts/
└── check-migrations.sh # wird ausgeführt, nicht geladen
Zusatzdateien sind der Weg, eine SKILL.md kurz zu halten. Anthropic empfiehlt unter 500 Zeilen und ausführliche Referenzen in eigenen Dateien. Skripte werden ausgeführt, ihr Quelltext belegt keinen Kontext.
Welche Frontmatter-Felder sind wichtig?
Kein Feld ist Pflicht. Diese machen in der Praxis den Unterschied:
| Feld | Wirkung |
|---|---|
description | Wann Claude den Skill von selbst nutzt. Das wichtigste Feld: konkret beschreiben, bei welchen Anfragen er passt. |
name | Name des Slash-Befehls; ohne Angabe der Verzeichnisname. |
allowed-tools | Werkzeuge, die Claude während des Skills ohne Rückfrage nutzen darf. |
disable-model-invocation: true | Nur Sie können den Skill aufrufen, Claude nicht von selbst. Sinnvoll für Deployments und alles mit Nebenwirkungen. |
user-invocable: false | Nur Claude nutzt den Skill, er erscheint nicht als Slash-Befehl. Sinnvoll für reines Hintergrundwissen. |
argument-hint | Hinweis auf erwartete Argumente, etwa [issue-nummer]. |
model | Eigenes Modell für diesen Skill, etwa ein günstigeres für Routinearbeit. |
context: fork | Der Skill läuft als Subagent in eigenem Kontext. |
Die Beschreibung wird zusammen mit when_to_use nach 1.536 Zeichen abgeschnitten. Wichtiges gehört an den Anfang.
Skill, Command, Hook, Subagent oder MCP?
| Werkzeug | Wofür | Verlässlichkeit |
|---|---|---|
| Skill | Wissen und Abläufe, die Urteilsvermögen brauchen | Claude legt die Anweisung aus |
Command (.claude/commands/) | wie Skill, ältere Form | funktioniert weiter |
| Hook | Prüfungen, die immer laufen müssen | feuert garantiert beim Ereignis |
| Subagent | umfangreiche Teilaufgaben mit eigenem Kontext | liefert nur das Ergebnis zurück |
| MCP-Server | Anbindung externer Systeme | stellt Werkzeuge bereit |
Die häufigste Fehlbesetzung: Eine Sicherheitsregel steht als Anweisung in einem Skill. „Führe vor jedem Commit die Tests aus" ist eine Bitte. Ein Pre-Commit-Hook ist eine Regel.
Wann lohnt sich ein Skill?
Ein Skill lohnt sich, wenn Sie denselben Ablauf mehr als zweimal erklären, wenn er Teamwissen enthält, das nicht in jeder Sitzung gebraucht wird, oder wenn ein Teil davon als Skript besser aufgehoben ist als im Prompt.
Er lohnt sich nicht für Regeln, die in jeder Sitzung gelten. Die gehören in die CLAUDE.md. Und er ersetzt keine Prüfung, die garantiert laufen muss.
Ein Nebeneffekt: Abläufe aus der CLAUDE.md in Skills zu verschieben, senkt den Tokenverbrauch jeder Sitzung. Wie stark sich das auf die Rechnung auswirkt, steht in Was kostet Claude Code?.
Skills im Team einführen
- Mit zwei oder drei Abläufen beginnen, die heute am häufigsten erklärt werden.
- Projekt-Skills im Repository ablegen und per Pull Request ändern.
- Die
descriptionan echten Anfragen testen: Wird der Skill genutzt, wenn er soll, und bleibt er still, wenn nicht? - Alles mit Nebenwirkungen auf
disable-model-invocation: truesetzen.
Wenn Claude Code nicht nur im Team eingerichtet, sondern Teil eines KI-Produkts werden soll, beginnt das bei mir mit der Produkt-Discovery. Die Umsetzung läuft als KI-Produktentwicklung.
Kostenloses Erstgespräch buchen
Quellen und Stand
Gelesen am 23. September 2026.
- Claude Code Docs: Skills – Aufbau, Speicherorte, Frontmatter, Commands
- Claude Code Docs: Features Overview – Abgrenzung zu Hooks, Subagenten und MCP
- Claude Code Docs: Manage costs – Skills statt langer CLAUDE.md
- Agent Skills Standard
Weiterlesen
- Der .claude-Ordner in Claude Code erklärt
- Claude Code Hooks Cookbook
- CLAUDE.md Template für Engineering-Teams
- Was kostet Claude Code?
Häufig gestellte Fragen
Häufige Fragen
Was ist ein Skill in Claude Code?
Ein Skill ist ein Verzeichnis mit einer Datei SKILL.md, die Anweisungen für eine bestimmte Aufgabe enthält, optional mit Zusatzdateien und Skripten. Claude Code lädt den Skill, wenn er zur Aufgabe passt, oder Sie rufen ihn direkt mit /skill-name auf.
Wo liegen Claude Code Skills?
Persönliche Skills unter ~/.claude/skills/<name>/SKILL.md, Projekt-Skills unter .claude/skills/<name>/SKILL.md im Repository, Plugin-Skills im skills-Ordner des Plugins. Unternehmen können Skills zusätzlich über verwaltete Einstellungen verteilen.
Was ist der Unterschied zwischen Skills und Slash Commands?
Anthropic hat Custom Commands in Skills überführt. Eine Datei unter .claude/commands/ funktioniert weiter und erzeugt denselben Slash-Befehl wie ein Skill. Skills können zusätzlich Dateien mitbringen, von Claude selbstständig genutzt werden und eigene Frontmatter-Felder wie allowed-tools haben.
Welche Felder braucht die SKILL.md?
Laut Dokumentation ist kein Feld Pflicht; empfohlen ist description. Der name ergibt sich sonst aus dem Verzeichnisnamen. Häufig genutzt werden außerdem allowed-tools, disable-model-invocation, argument-hint und model.
Wann nehme ich einen Skill, wann einen Hook?
Ein Hook feuert garantiert bei seinem Ereignis, zum Beispiel vor jedem Commit. Ein Skill ist eine Anweisung, die Claude auslegt; das Ergebnis kann variieren. Prüfungen, die immer laufen müssen, gehören in Hooks. Wissen und Abläufe, die Urteilsvermögen brauchen, gehören in Skills.