Agent Skills in Claude Code installieren und nutzen: SKILL.md einfach erklärt

Schritt für Schritt zu Agent Skills in Claude Code: was SKILL.md macht, wo Skills liegen, wie du einen schreibst und wie du Skills reparierst, die nicht laden.

Flat illustration of a folder holding a SKILL.md document plugging into a terminal window

Wenn du Claude Code immer wieder dieselben Anweisungen einfügst, kann ein Skill sie für dich aufbewahren. Diese Anleitung zeigt, was ein Agent Skill ist, wo die Dateien hingehören und wie du einen kleinen Skill schreibst und testest. Außerdem geht es um die Installation von Skills aus Plugin-Marktplätzen und um die Fehler, die das Laden eines Skills verhindern.

Auf Mindloop Experience ansehen: Set Up Claude Code Like a Pro: Skills, MCP Servers & Plugins

Alles Folgende wurde im November 2026 mit der offiziellen Dokumentation von Anthropic abgeglichen. Claude Code ändert sich oft, daher haben die verlinkten Docs das letzte Wort.

Was ein Agent Skill ist

Ein Skill ist ein Ordner, in dem eine Datei namens SKILL.md liegt. Die Datei besteht aus zwei Teilen. Oben steht YAML-Frontmatter zwischen ----Markierungen mit einem name und einer description. Darunter folgen einfache Markdown-Anweisungen, die Claude befolgt, wenn der Skill läuft.

Ein Skill-Ordner kann auch zusätzliche Dateien enthalten, etwa Referenznotizen, Vorlagen oder Skripte.

Skills werden stufenweise geladen, was Anthropic Progressive Disclosure nennt. Beim Start lädt Claude nur Name und Beschreibung jedes Skills. Die vollständigen Anweisungen werden geladen, wenn der Skill ausgelöst wird, und mitgelieferte Dateien nur dann, wenn Claude sie öffnet. So kannst du viele Skills installieren, ohne das Kontextfenster zu füllen.

Was du brauchst

  • Claude Code, installiert und angemeldet
  • Ein Terminal und einen Texteditor
  • Ein Git-Projekt zum Testen (der Beispiel-Skill schreibt Commit-Nachrichten)

Schritt 1: Festlegen, wo der Skill liegt

Wo du einen Skill speicherst, entscheidet, welche Sitzungen ihn sehen. Die zwei Orte, die du am häufigsten nutzen wirst:

  • Persönlich: ~/.claude/skills/<skill-name>/SKILL.md. In all deinen Projekten auf diesem Rechner verfügbar.
  • Projekt: .claude/skills/<skill-name>/SKILL.md in einem Repository. In Sitzungen in diesem Repo verfügbar. Committe ihn, und dein Team bekommt ihn auch.

Daneben gibt es noch Enterprise-, verschachtelte und Plugin-Speicherorte. Haben ein persönlicher und ein Projekt-Skill denselben Namen, gewinnt der persönliche.

Ein Haken: Persönliche Skills in ~/.claude/skills/ werden von Cloud-Sitzungen und Cowork nicht gelesen. Dafür empfehlen die Docs, den Skill in deinem claude.ai-Konto zu aktivieren oder ihn ins Repository zu committen.

Schritt 2: Den Ordner anlegen

Wir bauen einen persönlichen Skill namens commit-message.

Terminal
mkdir -p ~/.claude/skills/commit-message

Erwartetes Ergebnis: Der Befehl gibt nichts aus. Der leere Ordner existiert jetzt.

Schritt 3: SKILL.md schreiben

Lege ~/.claude/skills/commit-message/SKILL.md an und füge Folgendes ein. Der Dateiname muss genau SKILL.md lauten.

Code
---
name: commit-message
description: Writes a clear git commit message from the staged changes. Use when the user asks for a commit message, wants to commit their work, or asks how to describe their changes.
---

# Commit message writer

1. Run `git diff --staged` to see what is staged.
2. If nothing is staged, say so and stop.
3. Write a subject line in the imperative mood, under 72 characters.
4. Leave one blank line, then add a short body that explains why the change was made.
5. Show the message in a code block. Do not run `git commit` unless the user asks.

Ein paar Hinweise zum Frontmatter:

  • name wird zu dem Befehl, den du eintippst. Lässt du ihn weg, verwendet Claude Code den Ordnernamen.
  • description liest Claude, um zu entscheiden, ob es den Skill nutzt. Schreib zuerst, was der Skill tut, dann, wann er eingesetzt werden soll.
  • Das öffnende --- muss in der allerersten Zeile der Datei stehen. Sonst behandelt Claude Code die ganze Datei als reinen Inhalt.

Claude Code akzeptiert weitere Felder, etwa disable-model-invocation und allowed-tools. Uploads auf claude.ai und die Skills API akzeptieren aber nur sechs: name, description, license, compatibility, metadata und allowed-tools. Wenn du bei name und description bleibst, bleibt dein Skill portabel.

Schritt 4: Testen

Stage eine kleine Änderung in einem beliebigen Git-Projekt und starte dann Claude Code.

Terminal
git add .
claude

Du kannst den Skill auf zwei Arten auslösen. Erstens: Frag in normalen Worten und lass Claude ihn anhand der Beschreibung erkennen:

Code
Can you write a commit message for what I've staged?

Oder ruf ihn direkt beim Namen auf:

Code
/commit-message

Erwartetes Ergebnis: Claude führt git diff --staged aus und antwortet mit einer Betreffzeile und einem kurzen Text in einem Codeblock.

Nach dem Bearbeiten musst du nicht neu starten. Claude Code überwacht ~/.claude/skills/ und das .claude/skills/ des Projekts und übernimmt Änderungen in der laufenden Sitzung.

Schritt 5: Zusatzdateien hinzufügen (optional)

Wenn ein Skill wächst, lagere Details aus SKILL.md aus. Die Docs empfehlen, die Datei unter 500 Zeilen zu halten. Eine Struktur könnte so aussehen:

Code
commit-message/
├── SKILL.md
├── examples.md
└── scripts/
    └── check-length.sh

Verlinke die Zusatzdateien aus SKILL.md, damit Claude weiß, wann es sie öffnen soll. Skripte werden ausgeführt, nicht in den Kontext geladen.

Schritt 6: Skills aus einem Plugin-Marktplatz installieren

Du musst nicht jeden Skill selbst schreiben. In Claude Code können Skills in Plugins gebündelt sein, und Plugins kommen aus Marktplätzen. Der offizielle Marktplatz von Anthropic, claude-plugins-official, wird automatisch hinzugefügt, wenn du zum ersten Mal eine interaktive Sitzung startest.

Auch das öffentliche Skills-Repository von Anthropic auf GitHub lässt sich als Marktplatz hinzufügen. Die README nennt diese Befehle:

Code
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

In einer Sitzung öffnet /plugin install das Plugin-Panel, in dem du das Plugin prüfen und vor der Installation einen Scope wählen kannst. Plugin-Skills haben einen Namespace: Ein Skill namens review in einem Plugin namens my-plugin läuft als /my-plugin:review.

Skills vs. MCP-Server vs. CLAUDE.md

CLAUDE.md enthält dauerhafte Fakten und Regeln, die in jeder Sitzung geladen werden, etwa „use pnpm“ (nutze pnpm) oder „tests live in tests/“ (Tests liegen in tests/). Halte sie kurz, denn sie ist immer im Kontext.

Skills enthalten Abläufe und Referenzmaterial, die nur manchmal wichtig sind. Anthropic rät, einen Skill anzulegen, wenn ein Abschnitt der CLAUDE.md zu einem Ablauf angewachsen ist oder wenn du immer wieder dieselbe Checkliste in den Chat einfügst.

MCP-Server verbinden Claude mit externen Tools und Daten, etwa einer Datenbank, einem Issue-Tracker oder einer Design-App. Ein Skill kann Claude erklären, wie es diese Tools gut nutzt, stellt die Verbindung aber nicht selbst her.

Skills außerhalb von Claude Code

Das gleiche Format funktioniert in allen Claude-Produkten. Laut Anthropics Übersicht lassen sich eigene Skills in Claude Code erstellen, über die Claude API hochladen oder in den Einstellungen von claude.ai hinzufügen. Auf claude.ai hochgeladene Skills müssen separat in die API hochgeladen werden.

Ein Hinweis zur Sicherheit

Ein Skill ist nicht nur Text. Er kann Skripte enthalten und Claude dazu bringen, Befehle auszuführen und Tools aufzurufen. Anthropic rät, Skills nur aus vertrauenswürdigen Quellen zu nutzen, also selbst geschriebene oder solche von Anthropic. Wenn du einen aus einer anderen Quelle ausprobierst, lies vorher jede Datei, auch die Skripte, und achte auf unerwartete Netzwerkaufrufe oder Dateizugriffe.

Häufige Fehler und Lösungen

Claude nutzt den Skill nie von selbst

Meist liegt es an einer vagen Beschreibung. „Helps with git“ (hilft bei Git) gibt Claude wenig zum Abgleichen. Schreib, was der Skill tut, und welche Formulierungen Leute tatsächlich verwenden würden. Du kannst Claude auch fragen: „What skills are available?“ (Welche Skills sind verfügbar?), um zu prüfen, ob er geladen wurde, und ihn mit /skill-name direkt ausführen.

Der Skill taucht gar nicht auf

Prüfe Pfad und Groß-/Kleinschreibung. Es muss ~/.claude/skills/<skill-name>/SKILL.md sein, mit der Datei in einem eigenen Ordner, nicht lose in skills/. Die Docs listen außerdem Zeichen auf, die ein Name nicht enthalten darf, etwa <, > oder ein Leerzeichen am Anfang oder Ende.

Das Frontmatter ist fehlerhaft

Lässt sich das YAML nicht parsen, lädt Claude Code den Hauptteil trotzdem, aber mit leeren Metadaten. /skill-name funktioniert weiterhin, aber Claude kann deine Beschreibung nicht abgleichen. Starte Claude Code mit claude --debug, um den Fehler zu sehen, oder führe claude plugin validate ~/.claude/skills aus, um fehlerhafte Dateien zu finden.

Regeln für das Namensformat

Für claude.ai und die API darf name nur Kleinbuchstaben, Ziffern und Bindestriche enthalten, höchstens 64 Zeichen lang sein und weder das Wort anthropic noch claude enthalten. Die description darf bis zu 1.024 Zeichen lang sein. Vermeide außerdem einen Ordner namens synced, den Claude Code für von claude.ai heruntergeladene Skills reserviert.

Änderungen werden nicht übernommen

Änderungen an bestehenden Skills werden ohne Neustart geladen. Hast du aber ein Skills-Verzeichnis auf oberster Ebene angelegt, das beim Start der Sitzung noch nicht existierte, führe /reload-skills aus. Bei neuen Plugins führe /reload-plugins aus oder starte Claude Code neu.

Der Skill springt zu oft an

Formuliere die Beschreibung genauer. Wenn du ihn nur von Hand ausführen willst, füge dem Frontmatter disable-model-invocation: true hinzu.

Fazit

Ein Skill ist ein Ordner, eine SKILL.md-Datei und eine gute Beschreibung. Fang mit einer Aufgabe an, die du jede Woche wiederholst, schreib die Schritte auf und teste sie mit einer normalen Anfrage und mit /skill-name. Prüfe alles, was du installierst, bevor du ihm vertraust.

Mehr zu Claude: Hier findest du alle unsere Anleitungen zu Claude und Anthropic, nach Aufgaben sortiert.

Quellen und offizielle Docs

Links zuletzt geprüft am 15. November 2026.

Von Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

Über Mindloop Experience

Kommentare

Kommentar schreiben

Mehr von Mindloop Experience

Alle Artikel von Mindloop Experience

Du kannst bis zu 50-mal applaudieren.