Ein Skill ist im Kern nichts anderes als ein Ordner mit einer einzigen Textdatei, die Claude beibringt, wie eine bestimmte Aufgabe in deinem Unternehmen ablaufen soll, einmal aufgeschrieben statt jedes Mal neu erklärt. Wer schon mit Claude Code oder Claude Cowork arbeitet, aber noch keinen eigenen Skill gebaut hat, verschenkt genau die Wiederholung, die sich am leichtesten automatisieren lässt. Diese Anleitung zeigt Schritt für Schritt, wie eine eigene SKILL.md entsteht, welche Felder Pflicht sind und woran die meisten ersten Versuche scheitern.
Exaktes Maßnehmen vor dem ersten Schnitt. Genau diese Präzision braucht auch eine SKILL.md: erst die Schritte sauber festlegen, dann läuft die Ausführung von selbst. Foto: www.kaboompics.com auf Pexels
name und description sowie einer Anleitung in normaler Sprache besteht. Claude lädt zuerst nur die Kurzbeschreibung aller installierten Skills, liest den vollen Inhalt aber erst, wenn eine Anfrage dazu passt, wodurch beliebig viele Skills ohne Mehrkosten bereitliegen können. Angelegt wird ein Skill wahlweise als Zip-Upload in claude.ai, als Ordner in Claude Code oder über die Skills-API, je nachdem, wer ihn nutzen soll. Entscheidend für den Erfolg ist die description, denn nur an ihr erkennt Claude, wann der Skill greifen soll, und ein sauberer Vorher-Nachher-Test in einer frischen Sitzung zeigt, ob er das wirklich tut.Was eine SKILL.md tatsächlich ist
Ein Skill besteht aus einem Ordner, der mindestens eine Datei enthält: SKILL.md. Der Name des Ordners wird später zum Befehl, mit dem du den Skill direkt aufrufst. Die Datei selbst hat zwei Teile: einen YAML-Kopf zwischen zwei Linien aus drei Bindestrichen mit den Metadaten, und darunter normalen Markdown-Text mit der eigentlichen Anleitung.
---
name: angebot-nachfassen
description: Erstellt eine höfliche Nachfass-Mail für ein offenes Angebot. Nutze dies, wenn nach einem Angebot ohne Rückmeldung ein Erinnerungstext gebraucht wird.
---
## Vorgehen
1. Frage nach Firmenname, Ansprechpartner und Datum des Angebots, falls nicht bekannt.
2. Schreibe eine kurze, freundliche Nachfass-Mail auf Deutsch, maximal 120 Wörter.
3. Biete einen konkreten nächsten Schritt an, zum Beispiel einen kurzen Rückruf.Genau das ist bereits ein vollständiger, funktionsfähiger Skill. Kein Code, keine Installation, keine Programmierkenntnisse, nur eine Textdatei, die genauso aufgebaut ist wie eine kurze Einarbeitung für einen neuen Mitarbeiter: was zu tun ist, in welcher Reihenfolge, und woran sich die Aufgabe erkennen lässt. Wer die Grundlagen zu Claude selbst noch nicht kennt, findet den Einstieg in unserem Beitrag Was ist Claude?.
Wie Claude einen Skill lädt, ohne Kontext zu verschwenden
Der Grund, warum sich beliebig viele Skills anlegen lassen, ohne dass jede Anfrage langsamer oder teurer wird, liegt in einem gestuften Ladeverfahren. Anthropic nennt das Prinzip progressive disclosure, und es funktioniert in drei Stufen:
Beim Start lädt Claude ausschließlich Name und description aus dem YAML-Kopf jedes installierten Skills, ein winziger Textschnipsel pro Skill. Erst wenn eine Anfrage inhaltlich zur description passt, liest Claude den vollständigen Text der SKILL.md nach. Verweist die Anleitung zusätzlich auf weitere Dateien, etwa eine Vorlage oder ein Skript, öffnet Claude auch die erst dann, wenn sie tatsächlich gebraucht werden. Ein Skill mit einer ausführlichen Referenzdatei kostet also nichts, solange niemand danach fragt.
Nicht jeder Token in einem Skill hat sofort seinen Preis. Nimm nur den Kontext auf, den Claude nicht ohnehin schon kennt.
— Anthropic, Leitfaden zum Schreiben effektiver Skills, 2026
Für die Praxis heißt das: Die description ist der einzige Text, den Claude bei jeder einzelnen Anfrage im Hinterkopf hat. Alles andere darf ausführlich sein, solange es der description gelingt, den richtigen Moment zu treffen.
Die drei Orte, an denen ein eigener Skill leben kann
Bevor die erste Zeile geschrieben wird, lohnt sich die Entscheidung, wo der Skill überhaupt liegen soll, denn die drei Wege sind vollständig getrennt und gleichen sich nicht automatisch ab.
claude.ai: Unter Einstellungen lässt sich ein eigener Skill als Zip-Datei hochladen, verfügbar für Pro-, Max-, Team- und Enterprise-Konten mit aktivierter Code-Ausführung. Der Skill gehört dann nur dem eigenen Account, ein Admin kann ihn nicht zentral für das ganze Team verteilen.
Claude Code: Hier reicht ein Ordner mit einer SKILL.md-Datei, ganz ohne Upload. Unter ~/.claude/skills/ liegt ein Skill für alle eigenen Projekte bereit, unter .claude/skills/ innerhalb eines Projekts gilt er nur dort und lässt sich mit dem Projekt-Repository ins Team teilen.
Claude API: Über die Skills-Endpunkte hochgeladen, steht ein Skill dem gesamten Workspace zur Verfügung, also allen Kolleginnen und Kollegen, die auf denselben API-Zugang zugreifen. Das ist der richtige Weg, wenn ein Skill in eine eigene Anwendung eingebaut werden soll, etwa im Zusammenspiel mit den Kostenmodellen aus unserem Beitrag Claude API Kosten kalkulieren.
Schritt für Schritt: der eigene erste Skill
Schritt 1: Den Anwendungsfall eng zuschneiden. Der häufigste Fehler ist ein Skill, der zu viel auf einmal will. Am besten eignet sich eine einzelne, klar wiederkehrende Aufgabe, die sich in wenigen Sätzen beschreiben lässt, etwa die Nachfass-Mail aus dem Beispiel oben, ein bestimmtes Berichtsformat oder eine feste Prüfliste vor dem Versand eines Angebots.
Schritt 2: Den Ordner anlegen. In Claude Code reicht dafür ein einzelner Befehl im Terminal:
mkdir -p ~/.claude/skills/angebot-nachfassenDer Ordnername wird später zum Befehl /angebot-nachfassen. In claude.ai entfällt dieser Schritt, dort wird direkt eine SKILL.md-Datei geschrieben und anschließend als Zip hochgeladen.
Schritt 3: Die SKILL.md schreiben. Der YAML-Kopf zwischen den beiden Linien aus drei Bindestrichen bekommt mindestens name und description, darunter folgt die Anleitung in normaler Sprache. Das Beispiel weiter oben lässt sich direkt als Vorlage nehmen und auf die eigene Aufgabe anpassen.
Schritt 4: Testen, bevor der Skill für andere freigegeben wird. Eine Anfrage stellen, die zur description passen sollte, und beobachten, ob Claude den Skill von selbst zieht oder ob er direkt mit /angebot-nachfassen aufgerufen werden muss. Danach die gleiche Anfrage prüfen, wie sie ohne Skill beantwortet würde, um den tatsächlichen Unterschied zu sehen.
Schritt 5: Nachschärfen anhand der Beobachtung. Reagiert Claude gar nicht, ist meist die description zu vage. Reagiert Claude bei völlig anderen Themen, ist sie zu breit gefasst. Beides lässt sich direkt in der Textdatei korrigieren, ganz ohne Neuinstallation.
Die Pflichtfelder im Detail
Der YAML-Kopf verlangt zwei Angaben, beide mit festen Regeln, die Claude beim Anlegen eines Skills technisch prüft:
name: höchstens 64 Zeichen, ausschließlich Kleinbuchstaben, Ziffern und Bindestriche, keine XML-Zeichen, und die Wörter „anthropic” oder „claude” sind als Name nicht erlaubt.
description: darf nicht leer sein, höchstens 1024 Zeichen, ebenfalls ohne XML-Zeichen.
Für den Namen empfiehlt Anthropic eine Verb-Substantiv-Form wie rechnungen-pruefen oder angebote-schreiben statt vager Bezeichnungen wie „helfer” oder „tools”, damit auf einen Blick klar ist, wofür der Skill gedacht ist, gerade wenn im Laufe der Zeit mehrere Skills nebeneinander entstehen.
Die description ist die eigentliche Arbeit
Alles andere in der SKILL.md ist Ausführung, die description dagegen entscheidet, ob diese Ausführung überhaupt jemals aufgerufen wird. Claude wählt allein anhand dieses einen Textfelds aus, welcher von potenziell Dutzenden installierten Skills zu einer Anfrage passt, deshalb lohnt sich hier die meiste Sorgfalt.
Drei Regeln machen den Unterschied zwischen einem Skill, der zuverlässig greift, und einem, der ignoriert wird:
Immer in der dritten Person schreiben. Der Text landet unverändert im Systemprompt, und ein Wechsel der Perspektive verwirrt die Auswahl. Statt „Ich helfe dir bei Excel-Dateien” oder „Du kannst das für Tabellen nutzen” gehört dort „Analysiert Excel-Tabellen und erstellt Pivot-Auswertungen”.
Konkret sein und die Auslöse-Begriffe nennen. Eine description sollte sowohl beschreiben, was der Skill tut, als auch, wann er greifen soll. „Hilft bei Dokumenten” ist zu vage, um gegen andere Skills zu bestehen, „Erstellt Angebots-Nachfass-Mails, wenn ein Angebot ohne Rückmeldung nachgefasst werden soll” trifft den Anwendungsfall genau.
Lieber zu deutlich als zu zurückhaltend formulieren. In der Praxis übersieht Claude eher relevante Skills, als dass er zu viele auslöst, deshalb darf die description ruhig etwas nachdrücklicher formuliert sein, als es sich auf den ersten Blick natürlich anfühlt.
Wenn ein Skill wächst: mehrere Dateien statt einer langen SKILL.md
Für die meisten Fälle im Unternehmensalltag reicht eine einzelne, kurze SKILL.md vollständig aus. Wird eine Aufgabe komplexer, zum Beispiel weil mehrere Varianten oder eine ausführliche Referenz nötig sind, lässt sich ein Skill um weitere Dateien im selben Ordner erweitern:
angebot-nachfassen/
├── SKILL.md (Kurzanleitung, verweist auf die anderen Dateien)
├── tonalitaet.md (Beispiele für den richtigen Ton je nach Kunde)
└── vorlagen/
└── standard.md (Fertige Textbausteine)Claude öffnet tonalitaet.md oder die Vorlage nur dann, wenn die Aufgabe das tatsächlich verlangt, die Dateien kosten also nichts, solange sie nicht gebraucht werden. Anthropics eigene Richtlinie empfiehlt dabei, die SKILL.md selbst unter 500 Zeilen zu halten und Verweise nur eine Ebene tief zu setzen, damit Claude beim Nachlesen nicht durch mehrere verschachtelte Dateien springen muss. Wer bereits mit Claude Code arbeitet und wissen will, was sich über einzelne Skills hinaus automatisieren lässt, findet weiterführende Beispiele in unserem Beitrag Claude Code Skills 2026.
Typische Fehler beim ersten Versuch
Zu viele Aufgaben in einem Skill bündeln. Ein Skill, der gleichzeitig Angebote schreiben, Rechnungen prüfen und Berichte zusammenfassen soll, hat selten eine description, die für alle drei Fälle gleichermaßen präzise ist. Mehrere kleine Skills mit klarer Abgrenzung schlagen fast immer einen großen, unscharfen.
Erklärungen liefern, die Claude bereits kennt. Eine SKILL.md, die erst erläutert, was eine Rechnung ist, bevor sie zur eigentlichen Anweisung kommt, verschwendet Platz im Kontext, sobald der Skill geladen wird. Nur Informationen aufnehmen, die spezifisch für die eigene Firma oder Aufgabe sind, nicht allgemeines Wissen.
Den Skill nie mit echten Anfragen testen. Ein Skill, der nur einmal beim Schreiben überflogen wurde, zeigt seine Schwächen oft erst bei der zweiten oder dritten realen Anfrage, etwa wenn eine leicht andere Formulierung verwendet wird, als beim Schreiben der description vorausgesetzt.
Zeitgebundene Angaben einbauen. Eine Anleitung, die schreibt „aktuell gilt die alte Regelung, ab nächstem Quartal die neue”, veraltet zuverlässig. Besser ist ein klar benannter aktueller Stand plus ein separater Abschnitt für frühere Regelungen, falls die Historie relevant bleibt.
Der Testablauf, der zeigt, ob der Skill wirklich funktioniert
Dass Claude einen Skill lädt, zeigt nur, dass die description gefunden wurde, nicht, dass das Ergebnis auch besser ist. Der zuverlässige Test läuft in zwei Schritten: dieselbe realistische Anfrage einmal in einer frischen Sitzung mit aktivem Skill stellen, und einmal mit demselben Wortlaut ohne den Skill. Der Unterschied zwischen beiden Antworten zeigt ehrlich, ob der Skill tatsächlich etwas beiträgt, oder ob Claude ohnehin schon zum gleichen Ergebnis gekommen wäre.
Eine frische Sitzung ist dabei wichtig, denn eine Unterhaltung, in der der Skill gerade erst geschrieben wurde, kennt bereits den Kontext aus dem Schreibprozess selbst, was ein falsches Bild davon gibt, wie gut die Anleitung für sich allein funktioniert.
Häufige Fragen
Brauche ich Programmierkenntnisse, um einen Claude Skill zu erstellen?
Nein. Eine SKILL.md ist eine reine Textdatei mit einem kurzen YAML-Kopf und einer Anleitung in normaler Sprache, wie du sie auch einem neuen Kollegen geben würdest. Skripte und Code sind optional und nur für fortgeschrittene Fälle nötig.
Wo lege ich einen eigenen Skill an?
In claude.ai unter Einstellungen als Zip-Upload, in Claude Code als Ordner mit SKILL.md unter ~/.claude/skills/ für alle eigenen Projekte oder unter .claude/skills/ nur für ein bestimmtes Projekt, oder über die Skills-API im eigenen Workspace. Die drei Wege sind getrennt und synchronisieren nicht automatisch.
Was ist das Wichtigste in der SKILL.md-Datei?
Das description-Feld im YAML-Kopf. Claude entscheidet allein anhand dieses Textes, ob ein Skill zu einer Anfrage passt, deshalb muss er in der dritten Person stehen und konkret benennen, was der Skill tut und wann er greifen soll, statt vage zu bleiben.
Wie merke ich, ob mein Skill wirklich funktioniert?
Teste dieselbe realistische Anfrage einmal mit aktivem und einmal mit deaktiviertem Skill in einer frischen Sitzung und vergleiche die Ergebnisse. Nur ein Vorher-Nachher-Vergleich zeigt zuverlässig, ob der Skill greift und ob er tatsächlich bessere Ergebnisse liefert.
Quellen & Referenzen
- Anthropic: Offizielle Übersicht zu Agent Skills, Aufbau der SKILL.md, Pflichtfelder und Ladeverfahren. platform.claude.com
- Anthropic: Best-Practices-Leitfaden zum Schreiben effektiver Skills, insbesondere zur description und zu Progressive Disclosure. platform.claude.com
- Anthropic: Dokumentation zu Skills in Claude Code, Speicherorte und Testablauf. code.claude.com
- Anthropic: Engineering-Blogbeitrag zur Architektur von Agent Skills. anthropic.com
