Claude Code Skills: SKILL.md Dateien, die das Modell tatsächlich aufruft

Zuletzt aktualisiert: June 28, 2026

Ein Claude Code Skill ist ein Ordner mit einer SKILL.md Datei, die der Agent in den Kontext zieht, nur wenn eine Aufgabe darauf zutrifft. Ich habe mein erstes Skill erstellt, um nicht jedes Mal dieselbe 200 Wörter umfassende Datenbank-Migrations-Checkliste einzufügen. Diese einzelne Datei spart mir jetzt ungefähr eine Stunde pro Woche.

Hier ist die Kurzfassung und dann die praktische Anatomie: was ein Skill ist, wie man das SKILL.md Frontmatter und den Body schreibt, wie das Modell entscheidet, einen Skill aufzurufen, und wann ein Skill überdimensioniert im Vergleich zu einem einfachen Prompt ist. Wenn Sie bereits Claude Code verwenden, können Sie Ihr erstes Skill in unter fünf Minuten erstellen.

Kurzantwort: Was ist ein Claude Code Skill?

Ein Skill ist eine wiederverwendbare, vom Modell aufgerufene Fähigkeit, die als SKILL.md gespeichert wird (plus optional unterstützende Skripte). Im Gegensatz zu einem System-Prompt, der immer geladen wird, wird ein Skill bei Bedarf geladen, wenn das Modell entscheidet, dass er für Ihre Anfrage relevant ist. Sie schreiben einen Namen, eine Beschreibung dafür, wann man ihn verwenden soll, und die Body-Anweisungen. Die Beschreibung ist das wichtigste Feld überhaupt, denn anhand dessen liest das Modell, ob es den Skill auslösen soll. Skills leben lokal in .claude/skills/ oder werden aus einem Registry geliefert, sodass ein Team eine kanonische Art zur Durchführung von Migrationen, Code-Reviews oder Releases teilen kann.

Wenn Sie einen breiteren Kontext zum CLI selbst wünschen, sehen Sie meinen Claude Code ultimate guide for 2026. Für den Unterschied zwischen Skills und immer aktiven Sub-Agents lesen Sie how I automated my workflow with Claude Code sub-agents.

Was ist ein Skill eigentlich, und woraus besteht er?

Ein Skill ist ein Verzeichnis. Das Minimum, das es benötigt, ist eine SKILL.md Datei. Optional kann es Skripte, Vorlagen oder Referenzdokumente bündeln, die mit dem Skill mitgegeben werden. Die Dokumentation zu Agent-Skills von Anthropic beschreibt einen Skill als ein verpacktes Set von Anweisungen und Ressourcen, das das Modell bei Bedarf laden kann (docs.anthropic.com/en/docs/agents-and-tools/agent-skills).

Ich betrachte einen Skill als eine benannte, versionierte Subroutine für das Modell. Drei Dinge unterscheiden ihn von einem langen Prompt:

1. Er ist optional. Das Modell lädt ihn nur, wenn eine Aufgabe der Beschreibung zu entsprechen scheint.
2. Er ist eingegrenzt (scoped). Sie können Dateien und Skripte anhängen, die nur für diese spezifische Fähigkeit Sinn ergeben.
3. Er ist teilbar. Der Ordner ist über Projekte und Teammitglieder hinweg portierbar.

Das CLI selbst ist Open Source, und die Skills-Konvention wird zusammen damit auf GitHub dokumentiert (github.com/anthropics/claude-code), wo ich überprüfe, wann sich das Verhalten zwischen den Releases ändert.

Wie strukturiert man eine SKILL.md Datei?

Die Datei hat zwei Teile: YAML Frontmatter und einen Markdown Body. Das Frontmatter sagt dem Modell wann es laufen soll; der Body sagt ihm was zu tun ist. Hier ist die Anatomie, die ich verwende.

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

Der Body besteht aus einfachem Markdown. Ich behalte drei Abschnitte bei: ein Ziel in einer Zeile, ein nummeriertes Verfahren und ein explizites „Stoppen und Bestätigen“-Gate. Der name muss mit dem Ordnernamen übereinstimmen. Die description sollte für das Modell geschrieben sein, nicht für einen Menschen, sodass sie wie eine Auslösebedingung klingt.

Ich habe dies direkt getestet. Mit einer vagen Beschreibung wie „hilft bei Datenbanken“ wurde der Skill auf unzusammenhängende SQL-Fragen ausgelöst. Nachdem ich es jedoch in „Use when the user asks to create, modify, or roll back a database migration“ umschrieben hatte, stieg die Präzision der Auslösung von etwa 60 Prozent auf zuverlässig. Die Beschreibung übernimmt das Routing, also verbringen Sie Ihre Bearbeitungszeit dort.

Wann sollte man etwas in einen Skill umwandeln?

Das ist die Frage, die mir am häufigsten gestellt wird. Meine Regel: Wenn ich denselben Block von Anweisungen dreimal innerhalb von zwei Wochen eingefügt habe und er länger als ein Absatz ist, dann wird es zu einem Skill. Unten finden Sie die Entscheidungsmatrix, die ich tatsächlich verwende.

Die zweite Achse ist die Kosten. Jeder geladene Skill fügt dem Kontext Tokens hinzu, daher ist ein großer, immer relevanter Anweisungsblock besser als Projekt-Level-Speicher oder ein benutzerdefinierter Befehl denn als Skill. Skills glänzen bei bedingt relevantem Fachwissen.

Ein konkreter Fall, in dem ich einen Skill geschrieben habe: Unser Release-Prozess erfordert das Aktualisieren eines Changelogs, das Hochsetzen von drei Versionsdateien, Tagging und das Posten einer Zusammenfassung an Slack. Ich schrieb es einmal als Skill, und jetzt sage ich „cut a release“ und das Modell führt die gesamte Checkliste in der richtigen Reihenfolge aus. Ein konkreter Fall, in dem ich dies nicht getan habe: ein einmaliges Refactoring einer Konfigurationsdatei. Das blieb ein Prompt.

Wie funktioniert das Muster des vom Modell aufgerufenen Skills?

Das Muster, das Skills magisch wirken lässt, ist, dass Sie sie nicht aufrufen. Sie beschreiben die Aufgabe, und das Modell liest die Beschreibungen der verfügbaren Skills und zieht den passenden heran. Dies ist in der offiziellen Claude Code Dokumentation dokumentiert (docs.anthropic.com/en/docs/claude-code).

Der Ablauf sieht so aus:

1. Sie geben eine Anfrage in natürlicher Sprache ein.
2. Das Modell sieht den name und die description jedes installierten Skills.
3. Es bewertet die Relevanz zu Ihrer Anfrage.
4. Der Body des gewinnenden Skills (und die gebündelten Dateien) gelangen in den Kontext.
5. Das Modell führt die Anweisungen aus.

Die praktische Konsequenz: Sie müssen die description so schreiben, als würden Sie einen Suchmaschinen-Eintrag für das Modell verfassen. Beginnen Sie mit dem Verb und dem Auslösebereich. Vergleichen Sie diese beiden Beschreibungen:

• Schwach: „Ein Skill zur Bearbeitung von git-Dingen.“
• Stark: „Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite.“

Der starke Text nennt die Auslöseverben und die Schutzmaßnahme (guardrail). Das macht den Aufruf zuverlässig. Wenn Sie Skills mit Tools miteinander verbinden, behandelt der Claude Code MCP integration guide wie externe Tool-Server neben Skill-Bündeln passen. Für das zugrunde liegende Protokoll, das sie verbindet, sehen Sie MCP and the model context.

Wie löst und debuggt man einen Skill?

Das Auslösen ist größtenteils automatisch, aber ich habe drei bewusste Techniken zur Steuerung und zum Debuggen.

• Seien Sie explizit. „Use the safe-migration skill“ zwingt es dazu. Nützlich, wenn die Beschreibung mehrdeutig ist.
• Listen Sie installierte Skills auf. Bitten Sie das Modell, die verfügbaren Skills und deren Beschreibungen aufzulisten. So bestätige ich, dass ein neuer Skill registriert wurde.
• Überprüfen Sie den Trace. Wenn ein Skill falsch ausgelöst wird, lese ich nach, welche Beschreibung übereinstimmte, und verfeinere die Auslöseformulierung.

Wenn ein Skill nicht ausgelöst wird, liegt die Ursache fast immer an der Beschreibung, nicht am Speicherort der Datei. Ich schreibe den ersten Satz um, sodass er mit „Use when...“ beginnt, und füge die spezifischen Verben hinzu. Das behebt es zu neun von zehn Mal.

Hier ist die Debug-Checkliste, die ich durchlaufe, in dieser Reihenfolge:

Skill versus Sub-Agent versus Slash Command

Diese drei Bereiche überlappen sich, und die Leute verwechseln sie ständig. Ich halte sie durch eine einfache Trennung auseinander.

• Skill: vom Modell aufgerufene Anweisungen plus optionale Dateien. Am besten für bedingte Expertise.
• Sub-Agent: eine separate Claude Code Instanz, die isolierte Arbeit leistet. Am besten für parallele, langlaufende Aufgaben. Mein sub-agent automation write-up geht hier tief ins Detail.
• Slash Command: ein Shortcut, den man absichtlich eingibt. Am besten für Dinge, die man immer bei Bedarf haben möchte.

Skills sind die einzige Art von den dreien, die das Modell für Sie wählt. Das ist ihre Superkraft und ihr Risiko: Ein falsch beschriebener Skill verschwendet Kontext stillschweigend.

Wie teilt man Skills und nutzt ein Registry?

Ein Skill ist nur ein Ordner, daher ist das Teilen im Prinzip trivial. Ich lege den Ordner unter .claude/skills/ in das Repo und committe ihn. Teammitglieder erhalten ihn beim Klonen. Für den Austausch über Teams hinweg pflegt die Community Registries und das offizielle Tooling zeigt auf gemeinsame Standorte.

Mein praktisches Setup:

1. Projekt-spezifische Skills im Repo behalten, versioniert.
2. Persönliche Skills in einem dotfiles Repo verwalten, das in .claude/skills/ symlinked ist.
3. Skill-Versionen beim externen Teilen fixieren, da eine Änderung der Beschreibung das Verhalten stillschweigend ändern kann.

Der ehrliche Vorbehalt beim Teilen: Ein Skill kodiert Annahmen über Ihren Stack. Ein Migrationsskill, der für Drizzle geschrieben wurde, wird in einem Prisma-Projekt zu falschen Ergebnissen führen, wenn die Beschreibung den Scope nicht schützt. Geben Sie immer das Framework und die Schutzmaßnahmen in der Beschreibung an und fügen Sie einen „Stoppen und Bestätigen“-Schritt vor destruktiven Aktionen hinzu. Ich habe dies auf die harte Tour gelernt, als ein geteilter Skill eine zerstörerische Überarbeitung auf dem falschen Branch durchführte, daher behandeln Sie jeden geteilten Skill als nicht vertrauenswürdig, bis seine Beschreibung das Gegenteil beweist.

Image credits

• Black screen with code text overlay on a developer workstation — photo by Pixabay on Pexels
• Close-up of programming code on a monitor during development — photo by Christina Morillo on Pexels
• Laptop showing a code editor during software development — photo by luis gomes on Pexels