Eigene Skills für Claude Code erstellen: Ein vollständiges Tutorial

Drei Sitzungen hintereinander habe ich dieselbe Sicherheits-Checkliste in Claude Code eingefügt. Die Checkliste enthielt die spezifischen Schwachstellenmuster unseres Teams — die IDOR-Prüfungen, die einzigartig für unser API-Design sind, die Session-Handling-Regeln für unseren Authentifizierungsablauf, die Datenschutzregeln für unsere PII-Felder. Jedes Mal wendete Claude sie perfekt an. Jedes Mal musste ich daran denken, sie einzufügen.

Der Moment, in dem Sie sich dabei ertappen, denselben Kontext wiederholt zu erklären, ist der Moment, in dem Sie einen Skill erstellen sollten.

TL;DR

Skills sind modellaufgerufene Erweiterungen — Claude entdeckt und wendet sie automatisch basierend auf dem Kontext an, ohne dass Sie sie explizit aufrufen müssen ¹. Der Schlüssel zu zuverlässigen Skills ist das description-Feld: Claude verwendet LLM-Reasoning (kein Keyword-Matching), um zu entscheiden, wann jeder Skill aktiviert wird ¹. Erstellen Sie Skills für Domänenwissen, das über Sitzungen hinweg gilt (Sicherheitsmuster, Code-Stil, Geschäftsregeln). Erstellen Sie keine Skills für einmalige Aufgaben — verwenden Sie stattdessen Slash-Befehle.

Voraussetzungen: Vertrautheit mit dem Erweiterungssystem von Claude Code. Für den Vergleich zwischen Skills, Befehlen und Subagenten siehe den Skills-Abschnitt des Leitfadens.

Wann Sie einen Skill erstellen sollten

Nicht jeder wiederholte Prompt verdient einen Skill. Das Entscheidungsframework:

Skills sind für Wissen, das Claude immer verfügbar hat. Slash-Befehle sind für Aktionen, die Sie explizit auslösen. Wenn Sie sich zwischen beiden entscheiden, fragen Sie sich: „Soll Claude dies automatisch anwenden, oder soll ich entscheiden, wann es ausgeführt wird?”

Ein häufiger Fehler: Einen Skill für etwas erstellen, das Sie einmal pro Woche tun. Ich habe einen git-rebase-helper-Skill erstellt, der sich bei jedem Git-bezogenen Prompt aktivierte — Rebases, Merges, Cherry-Picks, sogar git status. Die Beschreibung war zu breit gefasst, sie verunreinigte den Kontext in 80 % der Sitzungen, in denen sie nicht benötigt wurde, und konkurrierte mit anderen Skills um das 2-%-Kontext-Budget ¹. Die Lösung war, den Skill zu löschen und stattdessen einen Slash-Befehl zu verwenden: /rebase, wenn ich ihn tatsächlich brauchte. Skills sollten stabiles Domänenwissen kodieren, keine gelegentlichen Workflows.

Tutorial: Einen Code-Review-Skill erstellen

Schritt 1: Das Verzeichnis erstellen

Skills befinden sich an vier möglichen Speicherorten, vom breitesten zum engsten Geltungsbereich ¹:

Für dieses Tutorial erstellen wir einen persönlichen Skill:

mkdir -p ~/.claude/skills/code-reviewer

Schritt 2: SKILL.md mit Frontmatter schreiben

Jeder Skill benötigt eine SKILL.md-Datei mit zwei Teilen: YAML-Frontmatter (zwischen ----Markierungen), das Claude mitteilt, wann der Skill verwendet werden soll, und Markdown-Inhalt mit Anweisungen, denen Claude folgt, wenn der Skill aufgerufen wird ¹.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

Beachten Sie allowed-tools: Read, Grep, Glob — dies beschränkt den Skill auf schreibgeschützte Operationen. Der Code-Reviewer kann Dateien untersuchen, aber nicht ändern. Tool-Beschränkungen verhindern, dass Skills unbeabsichtigte Nebeneffekte haben.

Weitere nützliche Frontmatter-Felder neben name, description und allowed-tools ¹:

Ein Hinweis aus der offiziellen Dokumentation: context: fork „macht nur bei Skills mit expliziten Anweisungen Sinn, die von Isolation profitieren” ¹. Verwenden Sie es für Analyse-Skills (Code-Review, Sicherheitsaudit), bei denen Sie einen sauberen Kontext wünschen, nicht für Wissens-Skills, die sich in die Hauptkonversation einfügen sollen.

Schritt 3: Unterstützende Ressourcen hinzufügen

Skills können auf zusätzliche Dateien im selben Verzeichnis verweisen ¹:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Verweisen Sie aus SKILL.md mit relativen Links darauf:

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Claude liest diese Dateien bei Bedarf, wenn der Skill aktiviert wird, und verwendet dabei standardmäßige Dateilesewerkzeuge ¹. Halten Sie SKILL.md unter 500 Zeilen und verschieben Sie detailliertes Referenzmaterial in unterstützende Dateien ³ — kürzere Skill-Dateien reduzieren den Kontextinjektions-Overhead und halten Claude auf die aktuelle Aufgabe fokussiert.

Schritt 4: Aktivierung testen

Der Skill wird aktiviert, wenn Sie das nächste Mal eine Claude-Code-Sitzung starten. Testen Sie es:

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

Überprüfen Sie, ob der Skill geladen wurde, mit einer von zwei Methoden ¹:

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

Wenn der Skill nicht aktiviert wird, liegt das Problem fast immer am description-Feld. Siehe Schritt 5.

Schritt 5: Der entscheidende Schritt — die Beschreibung schreiben

Das description-Feld ist die wichtigste einzelne Zeile in Ihrem Skill. Folgendes passiert unter der Haube: Beim Sitzungsstart extrahiert Claude Code den name und die description jedes Skills und injiziert sie in Claudes Kontext. Wenn Sie eine Nachricht senden, verwendet Claude Language-Model-Reasoning — kein Regex, kein Keyword-Matching, keine Embedding-Ähnlichkeit — um zu entscheiden, ob ein Skill relevant ist. Die offizielle Dokumentation besagt: „Claude gleicht Ihre Aufgabe mit Skill-Beschreibungen ab, um zu entscheiden, welche relevant sind. Wenn Beschreibungen vage sind oder sich überschneiden, lädt Claude möglicherweise den falschen Skill — oder übersieht einen, der helfen würde” ¹.

Eine unabhängige Analyse des Claude-Code-Quellcodes bestätigt den Mechanismus: Skill-Beschreibungen werden in einen available_skills-Abschnitt des System-Prompts injiziert, und das Modell verwendet standardmäßiges Sprachverständnis, um relevante Skills zum Aufrufzeitpunkt auszuwählen ⁴. Das LLM-basierte Matching hat wichtige Auswirkungen darauf, wie Sie Beschreibungen verfassen.

Schlechte Beschreibung:

description: Helps with code

Claude hat keine Ahnung, wann dies aktiviert werden soll. „Helps with code” passt auf alles und nichts — und da das Matching auf LLM-Reasoning basiert, erzeugen vage Beschreibungen unvorhersehbare Aktivierungen.

Bessere Beschreibung:

description: Review code for bugs and issues

Zu vage. Welche Art von Bugs? Welche Art von Problemen? Wann sollte Claude dies anstelle seiner eingebauten Analyse verwenden?

Effektive Beschreibung:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

Die effektive Beschreibung funktioniert, weil sie Folgendes enthält: - Was sie tut: Code auf spezifische Problemtypen überprüfen - Wann sie eingesetzt wird: Bei der Untersuchung von Änderungen, PRs, Qualitätsanalyse - Trigger-Phrasen: review, audit, check — Wörter, die der Benutzer natürlicherweise tippt

Eine Einschränkung, die Sie kennen sollten: Alle Skill-Beschreibungen teilen sich ein Kontext-Budget, das „dynamisch auf 2 % des Kontextfensters skaliert, mit einem Fallback von 16.000 Zeichen” ¹. Wenn Sie viele Skills haben, halten Sie jede Beschreibung prägnant — eine ausführliche Beschreibung konkurriert mit anderen Skills um begrenzten Platz. Sie können das Budget über die Umgebungsvariable SLASH_COMMAND_TOOL_CHAR_BUDGET überschreiben ², aber die bessere Lösung sind kürzere, präzisere Beschreibungen.

Testen Sie verschiedene Beschreibungen. Starten Sie eine neue Sitzung, bitten Sie Claude, Code zu überprüfen, und prüfen Sie, ob der Skill aktiviert wird. Falls nicht, fügen Sie mehr Trigger-Phrasen hinzu. Falls er aktiviert wird, wenn er es nicht sollte, machen Sie die Beschreibung spezifischer.

Schritt 6: Basierend auf der Nutzung iterieren

Nach einer Woche Nutzung werden Sie Folgendes feststellen: - Muster, die der Skill prüfen sollte, aber nicht prüft — fügen Sie sie zu SKILL.md hinzu - Falsche Aktivierungen bei unzusammenhängenden Aufgaben — verschärfen Sie die Beschreibung, oder fügen Sie disable-model-invocation: true hinzu und erfordern Sie den expliziten Aufruf über /code-reviewer - Fehlender Kontext — fügen Sie unterstützende Ressourcendateien hinzu - Tool-Beschränkungen, die zu eng oder zu locker sind — passen Sie allowed-tools an

Skills sind lebende Dokumente. Die erste Version ist nie die endgültige Version.

Fortgeschritten: Skills als Prompt-Bibliothek

Über einzelne Skills hinaus funktioniert die Verzeichnisstruktur als organisierte Prompt-Bibliothek:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Jeder Skill kodiert eine andere Facette der Expertise Ihres Teams. Zusammen bilden sie eine Wissensbasis, aus der Claude automatisch basierend auf dem Kontext schöpft. Ein Junior-Entwickler erhält Anleitung auf Senior-Niveau, ohne danach fragen zu müssen.

Ein Hinweis zur Anzahl der Skills: Mehr Skills bedeuten mehr Beschreibungen, die um das Kontext-Budget konkurrieren ¹. Wenn Sie bemerken, dass Skills nicht aktiviert werden, führen Sie /context aus, um zu prüfen, ob welche ausgeschlossen werden. Priorisieren Sie weniger, gut beschriebene Skills gegenüber vielen vagen.

Skills mit Ihrem Team teilen

Persönliche Skills (~/.claude/skills/) gehören nur Ihnen. Verwenden Sie sie für persönliche Präferenzen, experimentelle Muster oder Expertise, die spezifisch für Ihren Workflow ist.

Projekt-Skills (.claude/skills/ im Repo-Stammverzeichnis) werden über Git geteilt ¹:

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Wenn Teammitglieder pullen, erhalten sie den Skill automatisch. Keine Installation, keine Konfiguration. Git-Distribution ist der effektivste Weg, um Expertise in einem Team zu standardisieren.

Richtlinien für geteilte Skills: - Halten Sie Projekt-Skills auf Domänenwissen fokussiert (Geschäftsregeln, Architekturmuster) - Behalten Sie persönliche Skills für Workflow-Präferenzen (Formatierung, Commit-Stil) - Dokumentieren Sie, warum der Skill existiert, in einem Kommentar am Anfang von SKILL.md - Überprüfen Sie Skill-Änderungen in PRs wie jeden anderen Code

Wichtigste Erkenntnisse

• Erstellen Sie einen Skill, wenn Sie sich dabei ertappen, Kontext erneut zu erklären. Wenn Sie dieselbe Checkliste dreimal einfügen, sollte es ein Skill sein.
• Das Beschreibungsfeld bestimmt alles. Claude verwendet LLM-Reasoning, um Ihre Anfragen mit Beschreibungen abzugleichen ¹. Investieren Sie mehr Zeit in die Beschreibung als in den Skill-Inhalt.
• Verwenden Sie allowed-tools, um Nebeneffekte einzuschränken. Schreibgeschützte Skills sollten auf Read, Grep, Glob beschränkt werden.
• Teilen Sie Projekt-Skills über Git. Verteilung von Teamwissen ohne Konfigurationsaufwand ¹.
• Überabstrahieren Sie nicht. Ein Skill für jedes Mikromuster erzeugt Wartungsaufwand und konkurriert um das Kontext-Budget. Erstellen Sie Skills für Expertise, die stabil, wiederverwendbar und wertvoll genug ist, um gepflegt zu werden.

Referenzen