SKILL.md Aufbau: Syntax-Referenz für Claude

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

SKILL.md · minimal---
name: mein-skill
description: Erstellt SEO-optimierte Meta-Tags für
deutsche Websites. Nutze bei: meta tags, seo tags,
title tag erstellen.
---

# SEO Meta-Tag Generator

## Anweisungen
1. Lies die URL oder den Seiteninhalt
2. Generiere Title Tag (max 60 Zeichen, Keyword vorn)
3. Generiere Meta Description (max 155 Zeichen, CTA)
4. Generiere OG-Tags für Social Sharing

## Regeln
- Sprache: Deutsch
- Keyword immer in den ersten 3 Wörtern des Titles
- Description endet mit Handlungsaufforderung

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

Skill-Ordner · Strukturmein-skill/
├── SKILL.md ← Pflicht: Hauptanweisungen
├── references/
│ ├── vorlage.html ← Optional: Templates
│ └── schema.json ← Optional: Datenstrukturen
└── scripts/
└── validate.py ← Optional: Ausführbarer Code

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.

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 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

Zum Thema: Web Dev for Vibe Coders, Der komplette Guide 2026