Claude Code Skills: Wann ein Skill, wann die CLAUDE.md

Ein Claude Code Skill ist ein Ordner mit einer Datei darin: SKILL.md, ein YAML-Kopf mit zwei Pflichtfeldern und darunter Markdown. Mehr verlangt das Format nicht. Die Entscheidung, die tatsächlich Arbeit macht, ist eine andere, und sie kommt später: was in einen Skill gehört und was in die CLAUDE.md, und an welchem Ort der Ordner liegen muss, damit ihn die Sitzung auch findet, die ihn braucht.

Beim zweiten Teil dieser Frage scheitern Bibliotheken, nicht an der Syntax. Ein Skill unter ~/.claude/skills gilt laut Dokumentation für alle deine Projekte auf diesem Rechner, aber nicht für Cowork- und Cloud-Sitzungen (code.claude.com/docs/de/skills). Wer eine Routine aufsetzt, die nachts ohne ihn läuft, merkt das an dem Tag, an dem die Routine das erste Mal ohne ihren Skill arbeitet.

Was sind Claude Code Skills?

Ein Skill ist verpacktes Verfahrenswissen, das der Agent bei Bedarf nachlädt.

Definition: Ein Agent Skill ist ein Verzeichnis, das mindestens eine SKILL.md enthält. Diese Datei trägt Metadaten, mindestens name und description, sowie Anweisungen, die einem Agenten sagen, wie er eine bestimmte Aufgabe ausführt. Zusätzlich kann ein Skill Skripte, Referenztexte, Vorlagen und andere Dateien mitbringen (Spezifikation, agentskills.io).

Der Mechanismus dahinter heißt progressive disclosure und läuft in drei Stufen, die die Spezifikation mit Größenordnungen versieht:

1. Metadaten, ungefähr 100 Token. Beim Start lädt der Agent von jedem verfügbaren Skill nur name und description, gerade genug, um zu wissen, wann er relevant sein könnte.
2. Anweisungen, empfohlen unter 5.000 Token. Passt eine Aufgabe zur Beschreibung, liest der Agent die vollständige SKILL.md in den Kontext.
3. Ressourcen, nur bei Bedarf. Dateien aus scripts/, references/ oder assets/ werden geladen, wenn sie gebraucht werden.

Daraus folgt die Eigenschaft, die Skills von jeder anderen Form von Anweisung unterscheidet: Du kannst dreißig davon vorhalten und zahlst dafür im Normalfall dreißig Beschreibungen, nicht dreißig Anleitungen. Die deutsche Dokumentation sagt denselben Satz aus der anderen Richtung: "Im Gegensatz zu CLAUDE.md-Inhalten wird der Text eines Skills nur geladen, wenn er verwendet wird, sodass umfangreiches Referenzmaterial fast nichts kostet, bis Sie es benötigen" (code.claude.com/docs/de/skills).

Das Format gehört dabei nicht Anthropic allein. Es wurde dort entwickelt, am 16. Oktober 2025 angekündigt und im Dezember 2025 als offener Standard veröffentlicht (claude.com/blog/skills). Im Client-Showcase auf agentskills.io standen am 25.09.2026 46 Produkte, darunter Cursor, VS Code, GitHub Copilot, Gemini CLI, Codex und Goose. Ein Skill, den du heute schreibst, ist also kein Einbahnstraßen-Format.

Wie ist eine SKILL.md aufgebaut?

Zwei Pflichtfelder im Kopf, danach Markdown ohne Formatvorschriften. Die ganze Minimalfassung passt in fünf Zeilen:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Hier stehen die Anweisungen.

Die Spezifikation setzt für beide Pflichtfelder harte Grenzen, und das ist die Stelle, an der die meisten deutschen Anleitungen ungenau werden:

Quelle: agentskills.io/specification, abgerufen am 25.09.2026.

Claude Code kennt darüber hinaus eigene Felder, die nicht in der Spezifikation stehen, unter anderem disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, paths und context. Und es rechnet anders: description und when_to_use zusammen werden in der Skill-Liste bei 1.536 Zeichen abgeschnitten (code.claude.com/docs/en/skills). Beide Zahlen sind richtig, sie messen nur Verschiedenes. Die 1.024 sind die Grenze des Formats, die 1.536 sind die Stelle, an der ein bestimmtes Produkt kürzt. Wer portabel bleiben will, hält sich an die kleinere.

Die description ist dabei nicht Beiwerk, sondern der Auslöser. Sie ist das Einzige, was beim Start im Kontext liegt, also die einzige Grundlage, auf der entschieden wird, ob dein Skill überhaupt geladen wird. Die Spezifikation empfiehlt deshalb ausdrücklich, dort konkrete Schlüsselwörter unterzubringen, an denen ein Agent die passende Aufgabe erkennt.

Wann gehört etwas in einen Skill und wann in die CLAUDE.md?

Tatsachen in die CLAUDE.md, Abläufe in einen Skill. Die Dokumentation formuliert den Schnitt als Beobachtung am eigenen Verhalten: Leg einen Skill an, wenn du immer wieder dieselben Anweisungen, dieselbe Checkliste oder dasselbe mehrstufige Verfahren in den Chat kopierst, oder wenn ein Abschnitt deiner CLAUDE.md zu einem Verfahren gewachsen ist statt eine Tatsache zu bleiben (code.claude.com/docs/en/skills).

Der Grund ist der Preis, nicht der Stil. Die CLAUDE.md wird in jeder Sitzung geladen, ob sie gebraucht wird oder nicht. Ein Skill kostet im Ruhezustand seine Beschreibung.

An unseren eigenen Dateien lässt sich der Schnitt nachrechnen. Die Regeldatei dieser Website ist 414 Zeilen lang und besteht aus Tatsachen: welche Next-Version gepinnt ist, warum die Datenbank in Frankfurt steht, welche Route statisch bleiben muss, was nie behauptet werden darf. Nichts davon ist ein Ablauf, und jede dieser Zeilen kann in jeder Sitzung gebraucht werden. Der Skill, der diesen Artikel schreibt, ist 1.390 Zeilen lang und besteht fast vollständig aus Reihenfolge: Nachfrage prüfen, SERP lesen, Kannibalisierung ausschließen, entwerfen, durch zwei blockierende Gates schicken, veröffentlichen. Diese 1.390 Zeilen in eine Regeldatei zu legen hieße, sie an jedem Tag zu bezahlen, an dem niemand einen Artikel schreibt.

Zwei Sätze als Faustregel, die du ohne unsere Dateien anwenden kannst:

• In die CLAUDE.md, was jemand wissen muss, der irgendetwas an diesem Projekt anfasst.
• In einen Skill, was jemand tun muss, der genau diese eine Aufgabe anfasst.

Wo liegen Skills, und warum ist das eine Betriebsentscheidung?

An vier Orten, und der Unterschied zwischen ihnen ist keine Geschmacksfrage. Die deutsche Dokumentation führt sie in einer Tabelle mit dem Titel "Wählen Sie, wo Skills geladen werden":

Quelle: code.claude.com/docs/de/skills, abgerufen am 25.09.2026.

Die fett gesetzte Einschränkung in der ersten Zeile ist der Punkt, an dem aus einer Ablagefrage eine Betriebsfrage wird. Solange du selbst im Terminal sitzt, ist ~/.claude/skills der bequemste Ort für alles. Sobald ein Lauf ohne dich startet, in der Cloud, aus einem frischen Checkout heraus, gibt es dieses Verzeichnis nicht. Der Lauf sieht nur, was im geklonten Repository liegt.

Daraus wird eine Zwei-Spur-Regel, und wir betreiben unsere Bibliothek genau so.

Wie sieht eine Skill-Bibliothek im Betrieb aus?

Sie besteht aus zwei Spuren mit unterschiedlichen Pflichten, nicht aus einem Ordner mit vielen Unterordnern.

Spur eins: Skills, die nur du aufrufst. Sie liegen unter ~/.claude/skills, gelten für alle deine Projekte und brauchen keine Versionierung, weil der Einzige, der sie liest, in derselben Sitzung sitzt, in der du sie änderst.

Spur zwei: Skills, die etwas anderes als du liest. Eine geplante Routine, ein Kollege, eine zweite Maschine. Diese Skills liegen in einem eigenen Repository, marcokohns/claude-skills, das die Routine bei jedem Lauf als zweite Quelle klont. Drei Dinge machen die Spur belastbar, und alle drei sind einmal fällig:

1. Der Pfad wird im Auftrag festgenagelt. Der Prompt der Routine nennt skills/create-blog-article/SKILL.md aus dem geklonten Repository, damit ein gleichnamiger Skill unter .claude/skills im Zielprojekt ihn nicht überdeckt. Ohne diese Zeile entscheidet die Ladereihenfolge, welcher Ablauf gefahren wird, und das merkt niemand, solange beide ähnlich genug aussehen.
2. Was nicht gepusht ist, existiert für den Lauf nicht. Der lokale Ordner ist bei uns ein Symlink in dieses Repository, Bearbeiten und Committen sind also derselbe Handgriff. Der Push ist es nicht, und er ist die einzige Stelle, an der ein vergessener Schritt still einen ganzen Lauf auf einen alten Stand setzt.
3. Die Historie ist die Begründung. 14 Commits seit dem 09.09.2026, neun davon an einem einzigen Skill. Jeder dieser neun trägt im Text den Grund, aus dem eine Regel dazukam, meistens ein Lauf, der ohne sie schiefgegangen ist.

Was hat das Nachmessen der eigenen Bibliothek gezeigt?

Dass das Feld, an dem alles hängt, das einzige ist, das niemand prüft. Wir haben die drei Skills am 25.09.2026 ausgezählt, und ein Ergebnis war unangenehm.

Ein Skill von dreien liegt mit 1.105 Zeichen über der Grenze von 1.024, die die Spezifikation setzt. Geschrieben hat ihn dieselbe Werkstatt, die ihre Artikel durch zwei blockierende Gates schickt. Dass es niemandem aufgefallen ist, hat einen simplen Grund: Eine zu lange Beschreibung wirft keinen Fehler. Sie wird stillschweigend gekürzt, und was verloren geht, steht am Ende, wo man die Feinheiten unterbringt. Der Skill lädt weiter, nur die Fälle am Rand seiner Beschreibung werden mit der Zeit seltener erkannt.

Die zweite Zahl ist ebenso eindeutig. Die Spezifikation empfiehlt, eine SKILL.md unter 500 Zeilen zu halten und Referenzmaterial in eigene Dateien auszulagern. Unser größter Skill hat 1.390 Zeilen und 116 Kilobyte, also das Zweieinhalbfache der Empfehlung, und lagert bisher nichts aus. Das ist kein Fehler, der etwas kaputt macht, es ist eine Rechnung, die bei jeder Aktivierung fällig wird. Die Spezifikation nennt den Ausweg im selben Absatz: Der Agent lädt beim Aktivieren die ganze Datei, also gehört alles, was nur manchmal gebraucht wird, in references/.

Zwei Prüfungen, die du in deiner eigenen Bibliothek in einer Minute machen kannst und die beide Funde hier gefunden hätten:

# Beschreibungen über 1.024 Zeichen
for f in skills/*/SKILL.md; do
  python3 - "$f" <<'PY'
import re, sys
t = open(sys.argv[1], encoding="utf8").read()
fm = re.match(r"---\n(.*?)\n---\n", t, re.S).group(1)
d = re.search(r"^description:[ ]*(.*)$", fm, re.M | re.S).group(1).strip()
print(sys.argv[1], len(d), "ZU LANG" if len(d) > 1024 else "ok")
PY
done

# SKILL.md über 500 Zeilen
wc -l skills/*/SKILL.md

Die offizielle Referenzbibliothek bringt dafür auch ein Prüfwerkzeug mit, skills-ref validate, das den YAML-Kopf gegen die Namenskonventionen prüft (agentskills.io/specification).

Woran scheitert ein Skill im Alltag?

An drei Stellen, und keine davon ist die Syntax der Datei.

Die Beschreibung ist zu allgemein. "Hilft bei PDFs" nennt die Spezifikation selbst als schlechtes Beispiel und stellt ihm eine Fassung gegenüber, die die Tätigkeiten aufzählt und den Auslösefall benennt. Da die Beschreibung das Einzige ist, was beim Start gelesen wird, entscheidet sie allein darüber, ob dein Skill je zum Zug kommt. Das ist auch der Grund, warum die Versuchung so groß ist, sie zu überladen, bis sie über 1.024 Zeichen hinausläuft.

Zwei Skills mit demselben Namen an verschiedenen Orten. Sobald derselbe Name persönlich, im Projekt und in einem Plugin vorkommt, entscheidet nicht mehr dein Vorsatz, welcher läuft. In einem Auftrag, der ohne dich läuft, gehört der Pfad deshalb ausgeschrieben.

Die Sammlung wächst schneller als ihre Begründung. Ein Skill, dessen Regeln niemand mehr erklären kann, wird beim nächsten Umbau vorsichtshalber behalten. Deshalb steht bei uns der Grund im Commit und nicht in einer Datei daneben. Wer eine Regel streichen will, liest, was sie einmal verhindert hat.

Welcher Skill ist dein erster?

Mit einem Ablauf, den du in diesem Monat zum dritten Mal in den Chat kopiert hast.

1. Leg ~/.claude/skills/<name>/SKILL.md an, mit name und description im Kopf und deinen Schritten darunter. Der Ordnername muss dem Feld name entsprechen.
2. Schreib die Beschreibung für die Auswahl, nicht für die Ausführung. Was der Skill tut und wann er dran ist, mit den Wörtern, die in deinen Aufträgen tatsächlich vorkommen, unter 1.024 Zeichen.
3. Entscheide vor dem zweiten Skill, welche Spur er ist. Wird er je von einem Lauf ohne dich gelesen, gehört er in ein Repository und nicht in dein Home-Verzeichnis. Danach umzuziehen ist möglich, aber du merkst den Bedarf erst an einem fehlgeschlagenen Lauf.

Welches Werkzeug überhaupt zu deiner Arbeitsweise passt, haben wir in Claude Code vs Cursor beantwortet, was der Monatsbetrag am Ende treibt, steht in Claude Code Kosten, und in welcher Sprache du deine Anweisungen schreibst, klärt Claude Code auf Deutsch. Einen einzelnen Auftrag in vier Blöcken baust du mit dem Prompt Generator, bevor du ihn zu einem Skill verdichtest.

Ein Skill allein ist noch keine Arbeitsweise. Dazu gehören Regeln, die auch dann gelten, wenn niemand hinsieht, Prüfungen, die einen Lauf anhalten statt ihn durchzuwinken, und Aufgaben, die zu Ende gehen, während du an etwas anderem sitzt. Genau das unterrichten wir auf Deutsch im Claude Code System, vier Wochen mit wöchentlichen Live-Sessions. Wer vorher sehen will, wie so eine Sitzung aussieht, kommt in ein kostenloses Live-Webinar. Alle Kurse stehen unter Kurse, und wer dahintersteckt, auf Über uns.