Claude Skill schreiben: SKILL.md-Struktur und echte Beispiele

So schreiben Sie einen Claude Skill in einem Satz: Legen Sie einen Ordner an, packen Sie eine SKILL.md-Datei hinein und schreiben Sie eine Description, die gut genug ist, damit Claude weiß, wann er darauf zugreifen soll. Das ist der ganze Mechanismus. Der Teil, der tatsächlich darüber entscheidet, ob Ihr Skill funktioniert, ist 1.024 Zeichen lang – das description-Feld, mit dem Anthropic Ihren Skill aus den mehr als 100 möglicherweise geladenen heraussucht. Wir betreiben 25 Skills in Produktion in der Techsy-Community-Library, und die, die scheitern, scheitern so gut wie nie an ihren Anweisungen. Sie scheitern an dieser einen Zeile.

Kurzfassung

So schreiben Sie einen Claude Skill: (1) Legen Sie einen nach dem Skill benannten Ordner an, (2) fügen Sie eine SKILL.md mit YAML-Frontmatter (name und description) plus Markdown-Anweisungen hinzu, (3) schreiben Sie die Description in der dritten Person mit klaren Trigger-Wörtern, (4) halten Sie den Body unter 500 Zeilen und verlagern Sie Details in Referenzdateien, und (5) testen Sie ihn mit echten Aufgaben, bevor Sie ihm vertrauen.

Was ein Claude Skill wirklich ist

Ein Skill ist ein Ordner mit einer SKILL.md-Datei im Root-Verzeichnis. Mehr braucht es nicht. Diese Datei enthält zwei Dinge: Metadaten, die Claude sagen, wann der Skill zum Einsatz kommt, und Anweisungen, die Claude sagen, wie die Aufgabe nach der Aktivierung zu erledigen ist.

Dass das günstig bleibt, liegt an einem Lademodell, das Anthropic Progressive Disclosure nennt. Beim Start liest Claude nur name und description jedes installierten Skills, jeweils rund 100 Tokens. Die vollständige SKILL.md liest Claude nur, wenn Ihre Description zur vorliegenden Aufgabe passt, und gebündelte Referenzdateien nur, wenn die Anweisungen darauf verweisen. So können Sie einen großen, detaillierten Skill ausliefern, ohne bei jeder Anfrage dafür zu bezahlen. Einen laufenden Katalog davon finden Sie in unserer Skills-Library.

Das SKILL.md-Grundgerüst zum Nachbauen

Jeder Skill startet mit derselben Form. Hier die minimale Version, die funktioniert:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

Zwei ----Marker rahmen die Frontmatter ein. Darunter ist der Body reines Markdown. Über unsere 25 Skills hinweg hat sich eine Struktur bewährt, die schlicht und konsistent ist: ein einzeiliger Titel, dann eine nummerierte oder mit Bullets versehene Prozedur, dann etwaige Templates oder Beispiele. Wenn wir uns in Prosa versucht haben, hat Claude sie nur überflogen. Wenn wir Schritte geschrieben haben, hat Claude sie befolgt. Wer fertige Beispiele studieren will: Die 25 Skills auf der Techsy-Community-Seite sind alles lesbare SKILL.md-Dateien, die Sie öffnen und kopieren können.

Frontmatter-Regeln: name und description

Die Frontmatter hat genau zwei Pflichtfelder, und beide haben feste Grenzwerte, die Sie sich merken sollten, weil Anthropics Tooling sie validiert.

Eine nützliche Konvention aus Anthropics Best-Practices-Guide: Skills werden im Gerundium benannt, also processing-pdfs, writing-documentation, analyzing-spreadsheets. Das liest sich in einer Liste gut und beschreibt die Tätigkeit statt eines vagen Substantivs wie helper oder utils. Halten Sie name deckungsgleich mit dem Ordnernamen, damit beide nie auseinanderdriften. Die vollständigen Validierungsregeln finden Sie im Anthropic-Best-Practices-Dokument – das ist die verbindliche Quelle.

Eine Description schreiben, die tatsächlich triggert

Das ist der Abschnitt, den die meisten Tutorials auslassen – und genau er entscheidet, ob Ihre Arbeit überhaupt genutzt wird. Die description wird in den System-Prompt injiziert, und Claude liest sie, um zu entscheiden, ob der Skill überhaupt geladen wird. Ein perfekter Body hinter einer vagen Description ist ein Skill, der nie läuft.

Drei Regeln machen den Unterschied:

Schreiben Sie in der dritten Person. Die Description beschreibt den Skill, nicht Sie und nicht den Nutzer. Formulierungen in der ersten oder zweiten Person verwirren die Auswahl.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Nennen Sie sowohl das Was als auch das Wann. „Verarbeitet Daten" sagt Claude nichts darüber, welche Aufgabe passt. Benennen Sie die konkrete Fähigkeit und die konkreten Trigger.

Verwenden Sie die Wörter, die ein Nutzer tatsächlich eingeben würde. Wenn Leute „PR", „diff" und „code review" sagen, gehören diese Begriffe in die Description. Claude matcht darauf. Das ist die wirkungsvollste einzelne Änderung, die Sie an einem Skill vornehmen können, und sie kostet eine Zeile.

Progressive Disclosure und Dateistruktur

Sobald ein Skill über ein, zwei Bildschirmseiten hinauswächst, beginnt die Struktur eine Rolle zu spielen. Anthropics Vorgabe ist konkret: Halten Sie den SKILL.md-Body unter 500 Zeilen und verlagern Sie alles Längere in separate Referenzdateien, auf die der Body verlinkt. Diese Dateien kosten null Tokens, bis Claude sie tatsächlich liest.

So sieht ein erwachsen gewordener Skill aus:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Zwei Regeln halten das am Laufen. Erstens: Halten Sie Referenzen eine Ebene tief – verlinken Sie jede Datei direkt aus der SKILL.md, nie Datei-zu-Datei-zu-Datei, weil Claude tief verschachtelte Dateien unter Umständen nur mit einem Partial Read anschaut und Inhalte übersieht. Zweitens: Geben Sie jeder Referenzdatei über 100 Zeilen ein Inhaltsverzeichnis an den Anfang, damit ein Partial Read trotzdem den vollen Umfang zeigt. Anthropics Engineering-Beitrag zu Agent Skills erklärt die Architektur dahinter, falls Sie das tiefere Modell verstehen wollen. Sobald Ihr Skill anfängt, Tools zu orchestrieren, ist unser MCP-Katalog ein nützlicher Begleiter, um Server einzubinden.

Freiheitsgrade (und wann Sie Scripts hinzufügen sollten)

Nicht jede Anweisung sollte gleich strikt sein. Richten Sie aus, wie eng Sie einen Schritt skripten, danach, wie fragil dieser Schritt ist.

Wenn ein Schritt deterministisch ist, liefern Sie ein Script mit, statt Claude jedes Mal Code generieren zu lassen. Ein gebündeltes Script ist zuverlässiger, spart Tokens und bleibt zwischen den Durchläufen konsistent. Zwei Gewohnheiten halten Scripts ehrlich: Fehler im Script selbst behandeln, statt sie an Claude zu delegieren, und jede Konstante begründen, damit keine unerklärten Magic Numbers übrig bleiben. Hier unterscheiden sich Skills auch von Subagents, die ihre eigene Tool-Allowlist und ihren eigenen System-Prompt mitbringen; unsere Automations-Library sammelt Subagent-Beispiele, und Sie können die beiden Ansätze auf der Techsy-KI-Automatisierungsseite vergleichen.

Testen: eval-getriebene Skill-Entwicklung

Die besten Skill-Autoren schreiben Tests, bevor sie Dokumentation schreiben. Anthropic empfiehlt, zuerst Evaluationen zu bauen: Lassen Sie Claude drei repräsentative Aufgaben ohne den Skill durchlaufen, notieren Sie genau, woran es scheitert, und schreiben Sie dann nur so viel Anweisung, wie nötig ist, um diese Fehler zu beheben. So lösen Sie echte Probleme, statt imaginäre zu dokumentieren.

Ein praktischer Ablauf:

1. Wählen Sie drei echte Aufgaben aus, die der Skill übernehmen soll.
2. Führen Sie sie ohne geladenen Skill aus und notieren Sie, was scheitert.
3. Schreiben Sie die minimale SKILL.md, die diese Fehler behebt.
4. Testen Sie erneut mit geladenem Skill, idealerweise über Claude Haiku, Sonnet und Opus hinweg, denn ein Skill, der Opus gut anleitet, kann für Haiku zu wenig spezifiziert sein.
5. Beobachten Sie, wie Claude sich durch die Dateien bewegt. Ignoriert Claude eine Referenz, ist Ihr Link nicht prominent genug platziert. Liest Claude dieselbe Datei ständig neu, gehört dieser Inhalt in die SKILL.md.

Für eine praktische Schritt-für-Schritt-Anleitung, die einen Skill von Anfang bis Ende baut, hat unsere Schwesterseite ein vollständiges Claude-Skills-Tutorial; es ergänzt die Autoring-Regeln hier gut. Sie können Ihren Build auch mit unseren Enterprise-Build-Checklisten abgleichen.

Häufige Fehler, die einen Skill scheitern lassen

Die meisten kaputten Skills scheitern aus einem von wenigen Gründen:

• Eine Description, die für Menschen geschrieben ist. Marketing-Text liest sich schön und triggert nichts. Schreiben Sie für das Modell: Fähigkeiten und Trigger.
• Zu viele Optionen. „Verwende pypdf, oder pdfplumber, oder PyMuPDF, oder …" lässt Claude zögern. Geben Sie einen Default mit genau einem Fluchtweg vor.
• Tief verschachtelte Referenzen. Dateien, die auf Dateien verlinken, die auf Dateien verlinken, werden nur teilweise gelesen. Halten Sie alles einen Hop von der SKILL.md entfernt.
• Zeitkritische Anweisungen. „Vor August mach X" veraltet. Packen Sie überholte Vorgaben stattdessen in eine eingeklappte Notiz „alte Muster".
• Windows-Pfade. Verwenden Sie immer Forward Slashes; Backslashes brechen auf Unix-Runnern.
• Uneinheitliche Terminologie. Wählen Sie ein Wort für eine Sache („field", nicht „field/box/element/control") und nutzen Sie es durchgehend.

Das Muster hinter allen sechs: Ein Skill ist eine Anweisungssammlung für einen sehr fähigen Leser, der keine Geduld für Mehrdeutigkeit hat. Sagen Sie die konkrete Sache – einmal.

Über den Autor

Mert Batur Gurbuz ist Mitgründer von Techsy, University of Birmingham. Er und das Techsy-Team bauen KI-Agenten, Automatisierungssysteme und Voice/SDR-Pipelines für B2B-Kunden und pflegen die 25-Skill-Library, auf die dieser Guide durchgehend verweist. Vernetzen Sie sich auf LinkedIn. Weitere Builder-Guides gibt es im TECHSY.community-Blog.

Häufig gestellte Fragen

Wo liegen die Claude-Skill-Dateien?

Ein Skill ist ein Ordner mit einer SKILL.md-Datei darin. In Claude Code liegen persönliche Skills unter ~/.claude/skills/{skill-name}/ und Projekt-Skills unter .claude/skills/{skill-name}/. Bei der API und auf claude.ai laden Sie den Skill-Ordner hoch. Der Ordnername sollte mit dem name-Feld in der Frontmatter übereinstimmen.

Muss der Skill-Name mit dem Ordnernamen übereinstimmen?

Ja, halten Sie beide identisch. Das name-Feld darf höchstens 64 Zeichen lang sein, nur Kleinbuchstaben, Ziffern und Bindestriche verwenden und die reservierten Wörter „anthropic" und „claude" vermeiden. Die Übereinstimmung mit dem Ordnernamen verhindert ein Auseinanderdriften und macht den Skill in Konversation und Dokumentation leicht referenzierbar.

Wie lang darf eine SKILL.md sein?

Halten Sie den SKILL.md-Body für zuverlässige Performance unter 500 Zeilen. Ein hartes Token-Limit gibt es nicht, weil Referenzdateien und Scripts erst beim Lesen etwas kosten, aber eine aufgeblähte Hauptdatei konkurriert mit allem anderen im Context Window. Nähern Sie sich 500 Zeilen, teilen Sie Details in Referenzdateien auf, die direkt aus der SKILL.md verlinkt sind.

Warum triggert mein Skill nicht?

Fast immer liegt es an der Description. Claude wählt Skills, indem es die Aufgabe mit dem description-Feld abgleicht – ist Ihre vage oder in der ersten Person geschrieben, aktiviert sie nie. Schreiben Sie sie in der dritten Person, nennen Sie, was der Skill tut und wann er eingesetzt wird, und verwenden Sie genau die Wörter, die ein Nutzer für diese Aufgabe eingeben würde.

Was ist der Unterschied zwischen einem Skill, einem Subagent und einem MCP-Server?

Ein Skill ist ein Paket aus Anweisungen, das Claude bei Relevanz lädt. Ein Subagent ist ein eigenständiger Agent mit eigener Tool-Allowlist und eigenem System-Prompt, der eine delegierte Aufgabe übernimmt. Ein MCP-Server stellt externe Tools und Daten über das Model Context Protocol bereit. Skills beschreiben wie die Arbeit erledigt wird; MCP-Server liefern worauf sich diese Arbeit bezieht.

Kann ein Claude Skill Code ausführen?

Ja. Skills können ausführbare Scripts mitbringen, die Claude als Tools ausführt, statt sie in den Context zu lesen – das ist günstiger und zuverlässiger für deterministische Arbeit wie Validierung oder Dateikonvertierung. Machen Sie die Absicht in Ihren Anweisungen explizit: „führe dieses Script aus" für Ausführung, oder „siehe dieses Script" für Referenzmaterial.

Funktionieren Skills sowohl in der API als auch auf claude.ai?

Ja, auch wenn sich die Laufzeitumgebung unterscheidet. Auf claude.ai kann die Code-Execution-Umgebung Pakete von npm und PyPI installieren, während die Claude API weder Netzwerkzugriff noch Runtime-Paketinstallation hat. Listen Sie benötigte Pakete in Ihrer SKILL.md auf und bestätigen Sie, dass sie in der Zielumgebung verfügbar sind, bevor Sie sich darauf verlassen.

Wie viele Skills kann Claude gleichzeitig geladen haben?

Sehr viele, denn beim Start liegen nur name und description jedes Skills im Context, rund 100 Tokens pro Stück. Deshalb ist die Description so wichtig: Claude wählt womöglich aus über 100 Skills, und nur eine präzise Description sorgt dafür, dass Ihrer korrekt ausgewählt wird. Der vollständige Body lädt erst, wenn der Skill ausgewählt ist.