Eigenen Claude Skill erstellen: Schritt-für-Schritt-Anleitung mit SKILL.md

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

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

Claude Code Plugin: Seit die Plugin-Mechanik in Claude Code Skills mitbringt, liegt ein vierter Ort daneben. Ein Skill unter <plugin>/skills/<name>/SKILL.md gilt überall dort, wo das Plugin aktiviert ist, und trägt einen eigenen Namensraum in der Form plugin-name:skill-name. Für ein Team, das ein halbes Dutzend Skills gemeinsam ausrollt und aktuell halten will, ist das der sauberste Weg, weil Namenskollisionen mit persönlichen Skills damit ausgeschlossen sind. Welche Skills sich für den Anfang lohnen, zeigt unsere Übersicht im Skills-Katalog.

Ein Detail, das in der Praxis Zeit kostet: Cowork-Sitzungen und die Sitzungen in der Cloud, inklusive der zeitgesteuerten Routinen, lesen den persönlichen Ordner ~/.claude/skills/ auf deinem Rechner nicht. Sie laden die Skills, die für dein claude.ai-Konto freigeschaltet sind, plus die, die im geklonten Repository unter .claude/skills/ liegen. Ruft eine geplante Routine einen rein persönlichen Skill auf, meldet Claude Code ihn schlicht als nicht gefunden. Wer nachts etwas automatisch laufen lassen will, legt den Skill also ins Repository oder schaltet ihn im Konto frei.

Ein Skill, viele Werkzeuge: das Format ist offener Standard

Als dieser Beitrag im Juli erschien, war eine SKILL.md eine Sache zwischen dir und Claude. Inzwischen ist das Format als offener Standard veröffentlicht, dokumentiert auf agentskills.io. Entwickelt hat es Anthropic, freigegeben wurde es für alle, und die Liste der Werkzeuge, die dasselbe Format lesen, ist lang: Cursor, VS Code mit GitHub Copilot, Googles Gemini CLI, OpenAIs Codex, JetBrains Junie, OpenCode, Goose von Block, Roo Code, Kiro und rund drei Dutzend weitere.

Bei ChatGPT hört die Gemeinsamkeit allerdings auf. OpenAIs Codex liest die SKILL.md, in ChatGPT selbst heißt der Baustein Custom GPT und wird als Konfiguration im Konto angelegt, mit sieben Feldern im Configure-Tab und hochgeladenen Wissensdateien. Für die Planung zählt vor allem die Zugangsfrage: Seit dem 16. August 2026 legen persönliche ChatGPT-Konten (Free, Go, Plus, Pro) keine neuen GPTs mehr an und veröffentlichen auch keine. Gebaut wird nur noch in Business-, Enterprise- oder Edu-Arbeitsbereichen, und weil ChatGPT Business im Jahresabo 20 US-Dollar je Nutzer kostet und mindestens zwei Sitzplätze verlangt, beginnt der Einstieg bei 40 US-Dollar im Monat. Wie der Aufbau dort abläuft und woran Firmen später stolpern, steht in Eigenen Custom GPT bauen: Anleitung plus die Grenzen im Firmeneinsatz.

Für die Kalkulation im Unternehmen verschiebt das etwas. Die zwei Stunden, die jemand in eine gute Anleitung steckt, hängen nicht mehr am Werkzeug. Wechselt das Team in zwei Jahren die Umgebung, wandert der Ordner mit, weil die Pflichtfelder überall dieselben sind. Wo Claude sonst im Unternehmen ansetzt, bündelt unser Claude-Guide für Unternehmen.

Die Spezifikation kennt genau sechs Felder im YAML-Kopf. Pflicht sind name und description. Dazu kommen license für die Lizenz, compatibility für Umgebungsanforderungen (maximal 500 Zeichen, etwa „Requires git, docker, jq”), metadata als freie Sammlung eigener Schlüssel-Wert-Paare wie Autor und Versionsnummer sowie allowed-tools für vorab freigegebene Werkzeuge, das die Spezifikation selbst noch als experimentell führt.

Ob eine Datei sauber ist, prüft die Referenz-Bibliothek des Standards:

skills-ref validate ./mein-skill

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

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

Die Spezifikation setzt beim Namen drei weitere Regeln, an denen ein Upload sonst scheitert: Er darf weder mit einem Bindestrich beginnen noch mit einem enden, er darf keine zwei Bindestriche hintereinander enthalten (pdf—processing ist ungültig), und er muss dem Namen des Ordners entsprechen, in dem die SKILL.md liegt. Wer den Ordner später umbenennt, denkt also an das Feld.

Für die Benennung selbst empfiehlt Anthropic im Best-Practice-Leitfaden die englische Verlaufsform, also processing-pdfs oder analyzing-spreadsheets, weil sie die Tätigkeit direkt benennt. Substantiv-Formen wie pdf-processing oder deutsche Varianten wie angebote-nachfassen gelten als gleichwertige Alternative. Was in beiden Fällen scheitert, sind vage Bezeichnungen wie „helfer”, „tools” oder „daten”: Sie sagen weder dir noch Claude, wofür der Skill gedacht ist, und das rächt sich, sobald mehrere Skills nebeneinander liegen.

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.

Die Schalter, die nur Claude Code kennt

Über die sechs Felder der Spezifikation hinaus wertet Claude Code eigene Angaben im YAML-Kopf aus. Vier davon sind im Firmenalltag wirklich nützlich.

disable-model-invocation: true verhindert, dass Claude den Skill von sich aus zieht. Er läuft dann ausschließlich, wenn jemand /angebot-nachfassen tippt. Für alles, was etwas auslöst, also einen Versand, einen Deploy, eine Buchung, ist das die richtige Einstellung.

Mit allowed-tools gibst du Werkzeuge für die Dauer des Aufrufs ohne Rückfrage frei, mit disallowed-tools nimmst du umgekehrt welche aus dem Angebot, etwa Rückfragen an den Nutzer bei einem Skill, der unbeaufsichtigt laufen soll. Beide Freigaben gelten nur bis zur nächsten Nachricht.

argument-hint und arguments beschreiben Parameter, sodass /deploy staging im Skilltext als benannter Platzhalter ankommt statt als roher Textanhang.

context: fork schließlich führt den Skill in einem eigenen Unterkontext aus, was sich für lange Prüfläufe lohnt, deren Zwischenschritte das Hauptgespräch nicht zumüllen sollen.

Und hier liegt die Falle: Genau diese Felder kennt die offene Spezifikation nicht. Lädst du dieselbe Datei in claude.ai hoch oder schiebst sie über die Skills-API, antwortet die Validierung mit einer Meldung dieser Art:

Unexpected key(s) in SKILL.md frontmatter: argument-hint.
Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Wer denselben Skill an mehreren Stellen einsetzen will, hält den YAML-Kopf deshalb bei den sechs Standard-Feldern und legt die Claude-Code-Schalter nur in der Fassung ab, die im Repository liegt. Claude Code akzeptiert alle sechs Spec-Felder, in dieser Richtung geht es also ohne Anpassung.

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, noch nicht, dass das Ergebnis besser ausfällt. 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 unbestechlich, 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.

Anthropic geht im Best-Practice-Leitfaden noch einen Schritt weiter und empfiehlt, drei solcher Testszenarien aufzuschreiben, bevor die eigentliche Anleitung entsteht. Also erst Claude ohne Skill auf typische Aufgaben loslassen, notieren, wo es hakt, und die SKILL.md danach genau gegen diese Lücken schreiben. Wer umgekehrt vorgeht, dokumentiert oft Probleme, die es gar nicht gibt. Dazu kommt eine Empfehlung, die im Alltag gern untergeht: den Skill mit jedem Modell testen, mit dem er später laufen soll. Was für Opus knapp genug formuliert ist, kann für Haiku zu wenig Führung sein.

Beim Nachschärfen in Claude Code musst du nichts neu starten. Claude Code beobachtet die Skill-Verzeichnisse und zieht Textänderungen an der SKILL.md noch in derselben Sitzung nach. Nur wenn du ein Skill-Verzeichnis anlegst, das beim Start der Sitzung überhaupt nicht existierte, braucht es einen Neustart.

Learoy Eichholz

Lead KI-Automation & Digitale Businessentwicklung, Collective Brain GmbH · Hamburg

Learoy Eichholz verantwortet bei Collective Brain die KI-Automation und die digitale Businessentwicklung. In 15 Jahren E-Commerce hat er Online-Geschäfte von innen kennengelernt, vom Shopsystem über Logistik und Daten bis zur Conversion. Diese Praxis bringt er heute in KI-gestützte Automatisierung ein: Er verzahnt Tools, Daten und Abläufe so, dass Mittelständler manuelle Arbeit abbauen und schneller wachsen. Sein Anspruch ist Automatisierung mit messbarem Geschäftseffekt statt Technik um der Technik willen.

Beratung anfragen