Ein Claude Skill ist ein Ordner mit einer Markdown-Datei. Kein Framework, kein SDK, kein Build-Prozess. Aber zwischen einem Skill der funktioniert und einem der ignoriert wird liegt ein entscheidender Unterschied: die Struktur der SKILL.md.
Die minimale SKILL.md — in 30 Sekunden
Das ist alles. YAML-Frontmatter mit name und description, dann Markdown-Anweisungen. Claude liest diese Datei wenn die Aufgabe zur Description passt — und folgt den Anweisungen.
Die Dateistruktur für komplexe Skills
Progressive Disclosure ist das Kernprinzip. Claude lädt nur SKILL.md beim Start. Referenzdateien werden erst geladen wenn die Aufgabe sie braucht. Ein Skill kann hunderte Dateien enthalten — der Context-Verbrauch bleibt minimal.
Kernerkenntnis
Die Description entscheidet ob Claude deinen Skill überhaupt aktiviert. Sie ist wichtiger als der gesamte restliche Inhalt. Maximal 200 Zeichen, extrem spezifisch, mit Trigger-Wörtern die Nutzer tatsächlich verwenden.
Die 5 häufigsten Fehler
1. Vage Description. "Hilft bei verschiedenen Aufgaben" aktiviert nie. "Erstellt DSGVO-konforme Cookie-Banner für deutsche Websites" aktiviert sofort wenn jemand "Cookie Banner" sagt.
2. Zu viel in SKILL.md. Jeder Token in der Hauptdatei konkurriert mit dem Gesprächsverlauf. Lagere Details in Referenzdateien aus und verweise darauf.
3. Keine Beispiele. Claude versteht Anweisungen besser wenn er sieht wie das Ergebnis aussehen soll. Ein konkretes Beispiel spart zehn Sätze Erklärung.
4. Fehlende Trigger-Wörter. Schreib in die Description was Nutzer tatsächlich tippen — nicht was der Skill technisch tut. "Nutze bei: meta tags, seo tags, title tag erstellen" ist besser als "Generiert HTML-Meta-Elemente".
5. Secrets im Skill. API-Keys, Tokens und Passwörter gehören nie in eine SKILL.md. Nutze Umgebungsvariablen oder ein separates Credential-Management.
Skill hochladen und testen
Claude.ai: Einstellungen → Funktionen → Skills → ZIP hochladen. Der ZIP-Ordner muss den Skill-Ordner als Root enthalten.
Claude Code: Skill-Ordner in ~/.claude/skills/ ablegen. Wird automatisch erkannt und per /skill-name aufrufbar.
API: Upload über /v1/skills Endpoint. Skills werden organisationsweit geteilt.
Wer den Unterschied zwischen Skills und MCP-Servern verstehen will, findet die Abgrenzung im Artikel Claude Skills vs. MCP. Für eine vollständige Anleitung zum Skill-Erstellungsprozess empfehle ich Claude Skills erstellen.
Häufige Fragen zur SKILL.md
Wie lang darf eine SKILL.md sein?
Technisch unbegrenzt. Praktisch sollte die Hauptdatei unter 2.000 Wörter bleiben. Alles darüber in Referenzdateien auslagern — Claude lädt sie nur bei Bedarf.
Kann ein Skill andere Skills aufrufen?
Nicht direkt. Aber Claude kann mehrere Skills gleichzeitig laden und kombinieren. Diese Zusammensetzbarkeit ist eines der stärksten Features des Systems.
Funktioniert mein Skill auch in Cursor oder anderen Agents?
Ja — der Agent Skills Standard ist plattformübergreifend. Dieselbe SKILL.md funktioniert in Claude Code, Cursor, Gemini CLI und weiteren kompatiblen Tools.
Zum Thema: Web Dev for Vibe Coders — Der komplette Guide 2026
Quellen
Anthropic, "Agent Skills Overview" — platform.claude.com/docs
Anthropic, "Best Practices für die Skill-Erstellung" — platform.claude.com/docs
agentskills.io — Offener Agent Skills Standard