Ein Claude-Code-Skill ist ein Ordner mit einer SKILL.md-Datei darin: YAML-Frontmatter, das Claude sagt, wann der Skill zu verwenden ist, und Markdown-Anweisungen dafür, was zu tun ist, sobald er ausgelöst wird. Das ist das gesamte Modell. Um einen zu erstellen, legen Sie das Verzeichnis an, schreiben die zweiteilige Datei, und Claude lädt sie entweder automatisch, wenn Ihre Anfrage zur Beschreibung passt, oder Sie rufen sie direkt mit /skill-name auf. In den meisten Fällen kein Plugin-Build, kein Neustart. Wir betreiben die gesamte Content-Pipeline dieser Website als einen einzigen Claude-Code-Skill, daher hat die folgende Schritt-für-Schritt-Anleitung dieselbe Form, die wir in der Produktion verwenden, und ist kein Spielzeugbeispiel.
Skills sind wichtig, weil sie das ersetzen, wozu jeder Vielnutzer von Claude Code am Ende greift: dieselbe Checkliste oder mehrstufige Vorgehensweise immer wieder in den Chat einzufügen. Verlagern Sie diese Vorgehensweise einmal in einen Skill, und sie wird zu einer wiederverwendbaren, versionierten Fähigkeit, die nur bei Relevanz geladen wird. Laut Anthropics Engineering-Beitrag folgen Skills einem offenen Standard, der so gestaltet ist, dass ein Agent Fachwissen bei Bedarf hinzuzieht, statt es die ganze Zeit im Kontext mitzuführen.
Was ist ein Claude-Code-Skill?
Ein Skill ist die kleinste Einheit wiederverwendbarer Vorgehensweise in Claude Code. Strukturell ist es ein Verzeichnis, das eine erforderliche Datei enthält, SKILL.md, plus beliebige optionale Begleitdateien. Das Frontmatter trägt einen name und eine description; der Textkörper trägt die Anweisungen, denen Claude folgt, wenn der Skill läuft. Laut der Claude-Code-Dokumentation wird der Verzeichnisname zum Slash-Befehl, den Sie eingeben, und die Beschreibung ist das, was Claude liest, um zu entscheiden, ob der Skill automatisch geladen wird. Im Jahr 2026 wurden benutzerdefinierte Befehle in Skills zusammengeführt: Eine Datei unter .claude/commands/deploy.md und ein Skill unter .claude/skills/deploy/SKILL.md erzeugen beide /deploy und verhalten sich gleich, nur dass der Skill-Ordner zusätzlich Skripte und Referenzdateien bündeln kann. Wenn Sie schon einmal einen Slash-Befehl geschrieben haben, kennen Sie bereits 80 % der Skills.
Wo Skills liegen
Wo Sie den Ordner ablegen, entscheidet über seinen Geltungsbereich. Es gibt drei Ebenen, und die Wahl hängt davon ab, wer den Skill sehen soll:
| Ebene | Pfad | Verfügbar in |
|---|---|---|
| Persönlich | ~/.claude/skills/<name>/SKILL.md | Allen Ihren Projekten |
| Projekt | .claude/skills/<name>/SKILL.md | Nur diesem Repository (committen, um es mit dem Team zu teilen) |
| Plugin | <plugin>/skills/<name>/SKILL.md | Überall dort, wo das Plugin aktiviert ist |
Bei Namenskonflikten überschreibt Persönlich Projekt, und beides überschreibt einen mitgelieferten Skill gleichen Namens, sodass ein Projekt-Skill code-review das integrierte /code-review ersetzt. Projekt-Skills werden auch aus verschachtelten .claude/skills/-Ordnern geladen, wodurch ein Paket in einem Monorepo Skills mitliefern kann, die nur gelten, wenn Sie innerhalb dieses Pakets arbeiten. Für ein Team ist Projektebene und in Git committet fast immer die richtige Wahl: Alle erhalten automatisch dieselben Leitplanken, so wie eine gemeinsame AGENTS.md-Datei das Verhalten von Agenten über ein Repository hinweg standardisiert.
So erstellen Sie einen Claude-Code-Skill, Schritt für Schritt
Hier ist der vollständige Ablauf für einen echten, nützlichen Skill, der Ihre nicht committeten Änderungen zusammenfasst. Legen Sie zunächst das Verzeichnis in Ihrem persönlichen Skills-Ordner an:
mkdir -p ~/.claude/skills/summarize-changes
Speichern Sie dann Folgendes als ~/.claude/skills/summarize-changes/SKILL.md:
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff before committing.
---
Run `git diff` and `git status` to see staged and unstaged changes.
Summarize what changed, grouped by file, in plain language.
Flag anything risky: secrets, deleted tests, large deletions, or config changes.
End with a suggested Conventional Commit message.
Das war's. Öffnen Sie ein Git-Projekt, nehmen Sie eine Änderung vor, und fragen Sie entweder "Was habe ich geändert?" (Claude lädt den Skill automatisch, weil die Anfrage zur Beschreibung passt) oder geben Sie /summarize-changes ein, um ihn direkt auszuführen. Claude Code überwacht Skill-Verzeichnisse auf Änderungen, sodass Bearbeitungen unter ~/.claude/skills/ oder einem Projekt-.claude/skills/ innerhalb der Sitzung wirksam werden. Nur das Anlegen eines brandneuen Skills-Verzeichnisses auf oberster Ebene, das beim Start noch nicht existierte, erfordert einen Neustart.
Warum die Beschreibung alles entscheidet
Der mit Abstand häufigste Grund, warum ein Skill nie auslöst, ist eine schwache description. Sie ist keine Dokumentation, sie ist der Auslöser: Beim Start lädt Claude nur den Namen und die Beschreibung jedes Skills und entscheidet dann anhand dieses Textes, was hinzugezogen wird. Eine vage Beschreibung wie "Dashboard-Builder" lässt Claude raten. Anthropics eigener skill-creator rät dazu, Beschreibungen bewusst "aufdringlich" zu gestalten und sie mit Auslösekontexten vollzupacken: statt "How to build a dashboard" schreiben Sie "...use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a dashboard." Bringen Sie sowohl was der Skill tut als auch jeden Kontext, in dem er auslösen soll in der Beschreibung unter. Alle "Wann-zu-verwenden"-Informationen gehören dorthin, niemals im Textkörper vergraben. Wenn Ihr Skill nicht auslöst, korrigieren Sie die Beschreibung, bevor Sie irgendetwas anderes anfassen.
Progressive Disclosure: warum Skills günstig bleiben
Der Grund, warum ein Skill eine riesige Vorgehensweise fassen kann, ohne Ihren Kontext aufzublähen, ist Progressive Disclosure, ein Ladenmodell mit drei Ebenen. Ebene 1 sind die Metadaten (Name + Beschreibung, ~100 Wörter), die immer im Kontext sind. Ebene 2 ist der SKILL.md-Textkörper, der nur geladen wird, wenn der Skill auslöst. Ebene 3 sind gebündelte Ressourcen (Skripte, Referenzdokumente, Vorlagen), die nur geladen werden, wenn der Textkörper Claude auf sie verweist. So kostet Sie ein Skill mit einer 2.000 Zeilen langen Migrationsreferenz nur etwa 100 Tokens, bis zu dem Moment, in dem Sie sie tatsächlich brauchen. Die praktische Faustregel aus der Dokumentation: Halten Sie den SKILL.md-Textkörper unter 500 Zeilen, und wenn er darüber hinauswächst, lagern Sie Details in separate Dateien aus und verlinken Sie darauf.
summarize-changes/
├── SKILL.md # required: frontmatter + core instructions
└── references/ # optional: loaded only when SKILL.md points here
└── risk-rules.md
Dies ist dasselbe Prinzip, das MCP-Server kombinierbar hält: Fähigkeits-Metadaten günstig bereitstellen, die schweren Details bei Bedarf laden.
Kontrolle darüber, wer einen Skill aufruft
Standardmäßig können sowohl Sie als auch Claude jeden Skill aufrufen. Für alles mit Nebenwirkungen ist das nicht das, was Sie wollen, und Sie sollten sich nicht darauf verlassen, dass Claude sich für ein Deployment entscheidet, weil der Code "fertig aussieht". Fügen Sie disable-model-invocation: true zum Frontmatter hinzu, und nur Sie können den Skill auslösen, indem Sie seinen Slash-Befehl eingeben:
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Verwenden Sie dies für /commit, /deploy, /send-slack-message und jede unumkehrbare Aktion. Zwei verwandte Felder geben feinere Kontrolle: allowed-tools listet Tools auf, die der Skill ohne Berechtigungsabfrage verwenden darf, und disallowed-tools entfernt Tools aus dem Pool, solange der Skill aktiv ist (nützlich für eine Hintergrundschleife, die den Benutzer nie eine Frage stellen sollte). Greifen Sie bewusst zu diesen Feldern, nicht standardmäßig.
Skill vs. CLAUDE.md vs. MCP: was brauchen Sie?
Diese drei überschneiden sich genug, um Menschen zu verwirren, deshalb hier die Aufteilung:
| Ansatz | Lädt | Am besten für |
|---|---|---|
| CLAUDE.md | Immer im Kontext | Kurze, stets zutreffende Fakten über das Repository |
| Skill | Bei Bedarf, wenn relevant | Wiederholbare Vorgehensweisen und Checklisten |
| MCP-Server | Tool-Schemas, bei Bedarf | Anbindung an externe Systeme und Daten |
Das Erkennungsmerkmal für einen Skill ist eine Vorgehensweise: Wenn ein Abschnitt Ihrer CLAUDE.md von einem Fakt zu einer mehrstufigen Anleitung angewachsen ist, will er ein Skill werden, wo er nichts kostet, bis er verwendet wird. Ein Fakt bleibt in der CLAUDE.md. Eine Live-Verbindung zu Jira oder einer Datenbank ist ein MCP-Server. Viele reale Setups nutzen alle drei zusammen, und eine gute Wahl zu treffen ist Teil derselben Tooling-Kompetenz, die die AI-Coding-Tools, die 2026 wirklich taugen von den anderen abhebt.
Häufig gestellte Fragen
Was ist eine SKILL.md-Datei?
Sie ist die eine erforderliche Datei in einem Skill-Ordner. Sie enthält YAML-Frontmatter (mindestens name und description) zwischen ----Markierungen, gefolgt von Markdown-Anweisungen, denen Claude folgt, wenn der Skill läuft. Der Ordnername wird zum /slash-command, und die Beschreibung sagt Claude, wann der Skill von selbst zu laden ist.
Wo lege ich einen Claude-Code-Skill ab?
In ~/.claude/skills/<name>/SKILL.md für einen persönlichen Skill, der über all Ihre Projekte hinweg verfügbar ist, oder in .claude/skills/<name>/SKILL.md für einen Projekt-Skill, den Sie committen und mit Ihrem Team teilen. Plugins können ebenfalls Skills bündeln. Persönliche Skills überschreiben Projekt-Skills gleichen Namens.
Muss ich Claude Code nach dem Hinzufügen eines Skills neu starten? Meistens nein. Claude Code überwacht Skill-Verzeichnisse und erfasst hinzugefügte, bearbeitete oder entfernte Skills innerhalb der aktuellen Sitzung. Die Ausnahme ist das Anlegen eines Skills-Verzeichnisses auf oberster Ebene, das beim Sitzungsstart noch nicht existierte, was einen Neustart erfordert, damit das neue Verzeichnis überwacht werden kann.
Warum löst mein Skill nicht aus? Fast immer liegt es an der Beschreibung. Claude entscheidet allein anhand von Name und Beschreibung, ob ein Skill geladen wird, sodass eine vage Beschreibung bedeutet, dass Claude nicht erkennen kann, dass Ihre Anfrage passt. Schreiben Sie die Beschreibung um, sodass sie die genauen Aufgaben und Formulierungen benennt, die den Skill auslösen sollen, und machen Sie ausdrücklich klar, dass er auch auslösen soll, wenn der Benutzer das naheliegende Schlüsselwort nicht verwendet.
Kann ich verhindern, dass Claude einen Skill automatisch ausführt?
Ja. Fügen Sie disable-model-invocation: true zum Frontmatter hinzu. Dann können nur Sie den Skill auslösen, indem Sie seinen Slash-Befehl eingeben, was Sie bei allem mit Nebenwirkungen wollen, etwa beim Deployen oder beim Senden einer Nachricht.
Sources
- Claude Code Docs — Claude mit Skills erweitern: die maßgebliche Referenz zur SKILL.md-Struktur, zu Frontmatter-Feldern, Skill-Speicherorten, Aufrufsteuerung und Live-Änderungserkennung.
- Anthropic Engineering — Agenten mit Agent Skills für die reale Welt ausstatten: die Design-Begründung für Skills und der offene Standard.
- anthropics/skills — skill-creator SKILL.md: Best Practices aus erster Hand zum Schreiben von Beschreibungen, zur Strukturierung von SKILL.md und zu Progressive Disclosure.
- Offener Standard Agent Skills: der werkzeugübergreifende Standard, dem Claude-Code-Skills folgen.
Waqas Ahmed Waseer
Waqas Ahmed Waseer ist Entwickler und Automation-Builder mit über 8 Jahren Erfahrung im Aufbau von Produktivsystemen, die von mehr als 100.000 Menschen genutzt werden. Er baut individuelle Multi-Tenant-SaaS, KI-Automatisierung (n8n, LLM-Workflows, WhatsApp-Bots) und Hosting-Infrastruktur (WHM/cPanel, CloudLinux) — und ist der Macher von WaSphere, FlowMaticX und der Hosting-Marke WaseerHost. Über 100 Projekte für KMU, Agenturen und finanzierte Start-ups umgesetzt.
