Claude Code Skills erklärt: Was geladen wird, wann sie ausgelöst werden und wie man sie schreibt

Ohne das Branding ist ein Skill ein Verzeichnis mit einer erforderlichen Datei. SKILL.md beginnt mit YAML-Frontmatter, das einen name und eine description enthält, und setzt sich dann als gewöhnliche Markdown-Anweisungen fort. Der Ordner kann zudem Skripte enthalten, die von den Anweisungen aufgerufen werden, sowie Referenzdokumente und Asset-Templates. Das ist das gesamte Format, und es ist bewusst simpel: Ein Skill ist ein schriftlich fixiertes Verfahren, das so verpackt ist, dass ein Agent es finden kann.

---
name: brand-audit
description: Check UI code against the project design system. Use when reviewing components, screens, or PRs for hardcoded colors, off-scale spacing, or fonts that bypass the tokens in DESIGN.md.
---

# Brand audit

1. Read DESIGN.md at the repo root before judging anything.
2. Flag any literal hex value, arbitrary Tailwind color, or font-family
   that does not come from the token set.
3. Report violations as file:line with the token that should be used.

Dasselbe Format funktioniert mittlerweile über Claude Code hinaus: Es hat sich zu einer offenen Agent-Skills-Konvention entwickelt, die auch OpenAI's Codex und Cursor mit eigenen Discovery-Pfaden übernommen haben. Deshalb begleitet Sie ein einmal geschriebener Skill zunehmend über verschiedene Tools hinweg. Die Codex-Seite behandeln wir in Codex skills.

Claude Code liest Ihre Skills nicht in jede Konversation ein. Zu Beginn einer Sitzung wird nur der Frontmatter indexiert: Jeder Skill steuert seinen Namen und seine Beschreibung bei – ein paar Zeilen, nicht mehr. Der vollständige Inhalt, die Skripte und die Referenzdateien werden nur geladen, wenn Claude entscheidet, dass die aktuelle Aufgabe mit einer Beschreibung übereinstimmt, oder wenn Sie den Skill explizit aufrufen. Anthropic nennt dies Progressive Disclosure, und es ist die Design-Entscheidung, an der das gesamte Feature hängt.

Daraus ergeben sich zwei praktische Konsequenzen. Erstens: Die Installation von fünfzig Skills kostet Sie im Kontext fast nichts, das Sammeln ist also günstig; hundert Beschreibungen wiegen weniger als ein geladener Skill-Inhalt. Zweitens – und das ist der Punkt, den die Zusammenfassungs-Posts übersehen –, ist ein Skill mit einer schwachen Beschreibung zwar *installiert, aber unerreichbar*. Claude kann eine Aufgabe nicht mit „Hilft bei Frontend-Sachen“ abgleichen. Die Beschwerden in Reddit-Threads („Ich habe zwanzig Skills installiert und nichts hat sich geändert“) liegen meist daran: Die Inhalte waren in Ordnung, aber die Beschreibungen gaben dem Modell nie einen Grund, sie zu öffnen.

• ~/.claude/skills/<skill-name>/SKILL.md: persönliche Skills, verfügbar in jedem Projekt, das Sie öffnen.
• .claude/skills/<skill-name>/SKILL.md: Projekt-Skills, die im Repo committet werden, sodass jeder Collaborator und jede Agent-Sitzung Zugriff darauf hat.
• Plugins: Ein Plugin kann Skills zusammen mit Befehlen und Agenten bündeln, wodurch Teams ein Set mit einer einzigen Installation verteilen können.

Der Speicherort im Repo ist wichtiger, als es scheint. Ein persönlicher Skill optimiert Ihre Sitzungen; ein committeter Skill optimiert auch die Sitzungen Ihrer Teamkollegen und Ihres CI-Agenten. Alles, was einen Projektvertrag kodiert – wie wir UI prüfen, wie wir Migrationen schreiben, wie wir das Designsystem anwenden –, gehört in .claude/skills/ direkt neben den Code, den es steuert.

Claude Code bietet drei Orte für Wissen, die unterschiedliche Fragen beantworten. CLAUDE.md wird immer geladen: Sie ist für Constraints gedacht, die für jede Anfrage gelten. Jede Zeile darin kostet bei jedem Prompt Kontext, daher sollte sie kurz bleiben. Ein Skill wird bei Bedarf geladen: Er ist für Verfahren gedacht, die nur gelegentlich relevant sind, und kann lang sein, da er nichts kostet, bis er ausgelöst wird. Ein Subagent ist ein völlig separater Kontext: Er ist für Arbeiten gedacht, deren Zwischenergebnisse Ihre Sitzung verunreinigen würden.

Die Trennlinie für die vollständige Dateitaxonomie, einschließlich AGENTS.md und DESIGN.md, finden Sie in CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

1. 1

   Ausgehend von wiederholten Korrekturen

   Die besten Kandidaten für Skills sind Dinge, die Sie immer wieder tippen: die Review-Checkliste, die Sie einfügen, die Deployment-Sequenz, die Sie erneut erklären. Wenn Sie den Agenten dazu noch nie zweimal korrigieren mussten, benötigt er noch keinen Skill.

2. 2

   Zuerst die Beschreibung als Trigger-Bedingung schreiben

   Schreiben Sie vor den Anweisungen den Satz, der entscheidet, wann dieser Skill geladen wird: die Verben und Situationen, die eine passende Anfrage enthalten würde. Wenn Sie diese Situationen nicht benennen können, wird der Skill nicht ausgelöst – und das haben Sie so frühzeitig erkannt.

3. 3

   Den Body als ausführbare Prozedur gestalten

   Nummerierte Schritte, exakte Befehle, exakte Dateipfade. Verweisen Sie bei längeren Inhalten auf Dateien im Skill-Ordner. Ein Agent folgt einer Prozedur weitaus zuverlässiger, als er eine vage Richtung („Vibe“) interpretiert.

4. 4

   Auf Artefakte verweisen, nicht auf Adjektive

   Ein Skill, der besagt „halte die UI konsistent“, bewirkt nichts. Ein Skill, der besagt „lies DESIGN.md und verwende nur dessen Tokens“, funktioniert, weil die Beurteilung in eine Datei ausgelagert wurde, die der Agent öffnen kann. Platzieren Sie das Wissen in einem Artefakt und lassen Sie den Skill als Zeiger fungieren.

5. 5

   Durch Fragen testen, nicht durch Aufruf

   Testen Sie nicht mit einem expliziten Aufruf; das beweist nichts über den Trigger. Formulieren Sie eine Anfrage so, wie Sie es natürlich tun würden, und prüfen Sie, ob der Skill geladen wird. Wenn nicht, muss die Beschreibung überarbeitet werden, nicht der Body.

Design ist der perfekte Anwendungsfall für Skills und die ideale Illustration der oben genannten Artefakt-Regel. Anthropic liefert einen Frontend-Design-Skill für Claude Code aus, der einzelne Screens tatsächlich verbessert; wir haben ihn getestet und genau aufgeschrieben, was er kann und wo er versagt. Was ihm fehlt, ist das Gedächtnis zwischen den Screens: Der Skill transportiert Geschmack, aber nicht Ihre Werte, sodass Screen zwanzig von Screen eins wegdriftet. Geschmack lässt sich generalisieren; Identität nicht.

Die Lösung ist das Muster aus Schritt vier: Der Skill bleibt eine schlanke Prozedur, und die Identität lebt in einem Artefakt – einer DESIGN.md im Repository-Root mit echten Tokens, Typografie-Entscheidungen, Spacing-Regeln und Never-do-Regeln. Der Brand-Audit-Skill am Anfang dieser Seite umfasst nur zwölf Zeilen, weil alles, was er erzwingt, in dieser einen Datei definiert ist. Das ist ein Designsystem für einen Agenten: kein Plugin, sondern ein lesbarer Vertrag.

npx --yes identityforge@latest install --client claude-code

Das Skill-Format ist nicht mehr nur Claude-spezifisch, was für Ihre Investition entscheidend ist. OpenAIs Codex erkennt SKILL.md-Ordner unter .agents/skills/ und ~/.agents/skills/ und ruft sie mit $ auf; Cursor hat Agent Skills mit demselben On-Demand-Loading neben seinen permanent aktiven Rules eingeführt und steuert lange prozedurale Regeln hin zu Skills. Die Konvention konvergiert überall zur gleichen Form: Frontmatter, das bewirbt, ein Body, der anweist, und ein Laden, das auf Relevanz wartet. Skills, die Sie gegen Artefakte in Ihrem Repo schreiben, statt gegen die Eigenheiten eines einzelnen Tools, überstehen den Tool-Wechsel.