Agent Skill erstellen – Schritt für Schritt

Kurze Antwort: Eine Claude Agent Skill erstellst du, indem du einen Ordner mit einer SKILL.md-Datei anlegst, darin YAML-Frontmatter mit einer description schreibst und dann deine Anweisungen als Markdown darunter packst. Fertig.

Klingt einfacher als es klingt? Ist es wirklich. In diesem Tutorial baust du von null eine funktionierende Skill — und verstehst dabei, warum das System so schlau designt ist, wie es ist.

Falls du noch nicht weißt, was Skills überhaupt sind, lies kurz Was sind Claude Skills? — das gibt dir den nötigen Kontext. Wenn du dich fragst, wann du eine Skill statt einem MCP-Server oder Subagenten nehmen solltest, schau in Skills vs MCP vs Subagents.

Was du brauchst

Du brauchst keine Programmierkenntnisse. Wirklich. Eine Skill ist im Kern eine Textdatei mit ein paar Sonderzeichen am Anfang. Was du mitbringst:

Claude Code installiert (code.claude.com)
Einen Texteditor (VS Code, Notepad++, was auch immer)
10 Minuten Zeit

Das war’s.

Die Struktur einer Skill

Eine Skill ist ein Ordner. In diesem Ordner liegt mindestens eine Datei: SKILL.md. Alle anderen Dateien sind optional.

meine-skill/
├── SKILL.md          # Pflicht – hier stehen deine Anweisungen
├── referenz.md       # Optional – ausführlichere Doku
└── scripts/
    └── helper.sh     # Optional – Skripte, die Claude ausführen kann

Claude lädt den Inhalt der SKILL.md erst, wenn die Skill tatsächlich gebraucht wird — anders als CLAUDE.md, die immer im Kontext hängt. Das spart Tokens und macht große Wissensdatenbanken praktisch kostenfrei.

Wo du den Ordner hinlegst

Das entscheidet, wer die Skill nutzen kann:

Speicherort	Pfad	Gilt für
Persönlich	`~/.claude/skills/<skill-name>/`	Alle deine Projekte
Projektbezogen	`.claude/skills/<skill-name>/`	Dieses Projekt (und alle, die es klonen)

Faustregel: Persönliche Skills sind dein persönliches Werkzeugkasten. Projektbezogene Skills teilst du mit dem Team.

Eine SKILL.md schreiben (mit echtem Beispiel)

Eine SKILL.md besteht aus zwei Teilen: YAML-Frontmatter zwischen ----Markierungen — und darunter normales Markdown mit deinen Anweisungen.

Der Aufbau

---
description: "Was die Skill tut und wann Claude sie nutzen soll."
---

## Deine Anweisungen hier

Schritt 1: ...
Schritt 2: ...

Die Frontmatter-Felder

Alle Felder sind optional — aber description ist so wichtig, dass die offizielle Doku sie als “empfohlen” markiert. Ohne sie weiß Claude nicht, wann die Skill relevant ist.

Feld	Pflicht?	Wozu
`description`	Empfohlen	Erklärt Claude, wann die Skill geladen werden soll
`name`	Nein	Anzeigename in der Skill-Liste (Standard: Ordnername)
`disable-model-invocation`	Nein	`true` → Skill läuft nur manuell via `/skillname`
`allowed-tools`	Nein	Welche Tools Claude ohne Rückfrage benutzen darf
`context`	Nein	`fork` → Skill läuft in einem eigenen Subagenten
`argument-hint`	Nein	Hinweistext beim Autocomplete, z. B. `[dateiname]`

Tipp: Der Befehl, mit dem du die Skill aufrufst, kommt vom Ordnernamen — nicht vom name-Feld. Ein Ordner namens git-zusammenfassung → Befehl /git-zusammenfassung.

Ein echtes Beispiel: Commit-Nachrichten-Generator

Nehmen wir an, du schreibst ständig dieselbe Anweisung in den Chat: “Schau dir den Diff an und schreib mir eine saubere Commit-Nachricht auf Deutsch.” Zeit, das als Skill zu gießen.

Schritt 1: Erstelle den Ordner:

mkdir -p ~/.claude/skills/commit-nachricht

Schritt 2: Erstelle die SKILL.md:

---
description: >
  Schreibt eine deutsche Commit-Nachricht für die aktuellen Änderungen.
  Nutzen wenn der Nutzer fragt: "Was soll ich committen?", "Schreib mir
  eine Commit-Nachricht" oder ähnliches.
---

## Aufgabe

Analysiere die aktuellen nicht commiteten Änderungen:

!`git diff HEAD`

Schreibe dann eine Commit-Nachricht nach diesem Schema:

- **Erste Zeile** (max. 72 Zeichen): `typ(bereich): kurze Beschreibung`
  - Typen: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
- **Leerzeile**
- **Optionaler Body**: Was wurde geändert und warum (nicht wie)?

Antworte nur mit der fertigen Nachricht in einem Codeblock.

Das war’s. Keine Installation, kein Build-Schritt.

Das !`git diff HEAD“ ist ein besonderes Feature namens Dynamic Context Injection: Claude Code führt den Befehl aus und fügt das Ergebnis direkt in die Skill ein, bevor Claude es liest. So arbeitet die Skill immer mit echten aktuellen Daten.

Die Skill testen und verbessern

Testen geht in zwei Modi — und du kannst zwischen beiden wechseln:

Modus 1: Manueller Aufruf

Tippe einfach den Befehlsnamen mit Slash:

/commit-nachricht

Claude lädt die Skill und führt die Anweisungen aus. Du siehst in der Ausgabe, welche Skills geladen wurden.

Modus 2: Automatischer Aufruf

Claude erkennt aus der description, wann eine Skill passt. Schreib einfach:

Was soll ich committen?

Claude entscheidet selbst, ob /commit-nachricht hier hilfreich ist. Wenn nicht — dann ist deine description noch nicht präzise genug.

Was tun, wenn Claude die Skill nicht findet?

Das passiert. Meistens liegt es an einem dieser drei Punkte:

Beschreibung zu vage → Mach sie konkreter, nenne typische Formulierungen, die Nutzer verwenden würden.
Tippfehler im Frontmatter → YAML ist whitespace-sensitiv. Prüfe die Einrückung.
Neue Skill, noch kein Neustart → Claude Code erkennt neue Skills live ohne Neustart — aber nur, wenn der ~/.claude/skills/-Ordner schon beim Start der Session existierte. Existierte er nicht, brauchst du einmalig einen Neustart.

Iteration

Ändere die SKILL.md — Claude Code erkennt die Änderung sofort ohne Neustart. Du kannst so lange tweaken, bis die Beschreibung sitzt.

Skills teilen

Im Team: Projektbezogene Skill

Leg die Skill ins Repo statt ins persönliche Verzeichnis:

.claude/skills/commit-nachricht/SKILL.md

Jeder, der das Repo klont, bekommt die Skill automatisch. Das macht projektbezogene Skills ideal für Team-Workflows, Coding-Konventionen oder projektspezifische Dokumentation.

Mit der Community: GitHub

Du kannst Skill-Ordner einfach auf GitHub veröffentlichen. Die Community sammelt Skills unter github.com/anthropics/skills — dort findest du auch Beispiele zum Lernen.

Skills folgen dem offenen Agent Skills-Standard (seit Dezember 2025 von Anthropic open-sourced). Das bedeutet: Eine gut geschriebene Skill funktioniert nicht nur in Claude Code, sondern auch in Gemini CLI und anderen kompatiblen Agents.

Wie es weitergeht

Für echte Tools statt Wissen: einen MCP-Server bauen
Inspiration als Vorlage: nützliche Claude Skills
Skills im Alltag: Claude Code Workflows

FAQ: Eigene Agent Skill erstellen

Wie erstelle ich eine eigene Agent Skill?

Lege einen Ordner unter ~/.claude/skills/<name>/ (für persönliche Skills) oder .claude/skills/<name>/ (für Projektskills) an. Darin erstellst du eine SKILL.md mit YAML-Frontmatter (mindestens eine description) und deinen Anweisungen als Markdown darunter. Claude Code erkennt die Skill automatisch — ein Neustart ist nur nötig, wenn der skills/-Ordner beim Sitzungsstart noch nicht existierte.

Was muss in eine SKILL.md?

Technisch gesehen nur die Markdown-Anweisungen — alle Frontmatter-Felder sind optional. Praktisch ist description unverzichtbar: Ohne sie weiß Claude nicht, wann die Skill relevant ist, und wird sie nie automatisch laden. Füge immer eine klare, präzise description hinzu, die typische Nutzerbefehle benennt.

Wo speichere ich meine Skill?

Das hängt davon ab, für wen die Skill gedacht ist. Persönliche Skills gehören in ~/.claude/skills/<name>/SKILL.md — sie sind in allen deinen Projekten verfügbar. Projektskills gehören in .claude/skills/<name>/SKILL.md — sie sind Teil des Repos und damit für alle Teammitglieder verfügbar, die das Repo klonen.

Brauche ich Programmierkenntnisse?

Nein. Eine einfache Skill ist eine Textdatei mit Markdown. Wenn du fortgeschrittene Features wie dynamische Kontextinjektion (Befehle via !`befehl`) oder Skripte im scripts/-Ordner nutzen willst, hilft etwas Shell-Wissen — ist aber keine Voraussetzung. Der Einstieg funktioniert mit purem Text.

Kann ich einer Skill Argumente übergeben?

Ja. Schreib /skill-name mein-argument und nutze $ARGUMENTS im SKILL.md-Body, um den Wert einzufügen. Für mehrere benannte Argumente kannst du arguments: [name1, name2] ins Frontmatter schreiben und dann $name1, $name2 im Body referenzieren.

Was ist der Unterschied zwischen persönlicher und Projektskill?

Persönliche Skills (~/.claude/skills/) gelten maschinenübergreifend für alle deine Projekte. Projektskills (.claude/skills/) sind repositorybezogen — sie werden mit dem Repo geteilt und gelten nur, wenn Claude Code in diesem Verzeichnis läuft. Bei Namenskonflikten gewinnt die persönliche Skill.

Nächste Schritte

Du hast jetzt alles, um deine erste Skill zu bauen. Starte klein: Nimm eine Anweisung, die du regelmäßig in den Chat eintippst, und gieß sie in eine Skill. Fünf Minuten Arbeit, die du dir ab sofort für immer sparst.

Wenn du tiefer einsteigen willst: Die offizielle Dokumentation unter code.claude.com/docs/en/skills ist erstaunlich gut geschrieben. Und unter github.com/anthropics/skills findest du Beispiele aus der Community.

Fragen? Schreib sie in die Kommentare — ich bin gespannt, welche Skills ihr baut.