Agent Skills erklärt: So baust du deinen ersten Skill

Jeder KI-Agent ist nur so gut wie das Wissen, das Sie ihm vermitteln. Lange Zeit war die gängige Antwort, alles in einen riesigen System Prompt zu stopfen. Dies ist nicht skalierbar. Agent Skills lösen dieses Problem auf viel sauberere Weise. In diesem Blogbeitrag erkläre ich, was Agent Skills sind, warum sie große System Prompts schlagen und wie Sie Schritt für Schritt Ihren ersten Skill bauen können. Am Ende haben Sie einen kleinen, funktionierenden Skill, der in Claude Code und in vielen anderen KI-Tools läuft.

Was sind Agent Skills?

Ein Agent Skill ist im Kern nur ein Ordner. Der Ordner enthält eine erforderliche Datei namens SKILL.md und, falls Sie möchten, zusätzliche Skripte und Referenzdokumente. Die Datei SKILL.md besteht aus zwei Teilen. Eine kurze YAML-Frontmatter teilt dem Agenten mit, was der Skill tut und wann er ihn verwenden soll. Der Markdown-Body teilt dem Agenten mit, wie die Aufgabe ausgeführt werden soll. Der Agent liest die Frontmatter nur beim Start. Der Rest wird bei Bedarf geladen, wenn eine Aufgabe übereinstimmt.

Das Muster wurde im Oktober 2025 von Anthropic für Claude eingeführt. Kurz darauf, im Dezember 2025, veröffentlichte Anthropic es als offenen Standard unter agentskills.io. Seitdem ging die Adoption sehr schnell voran. Tools wie OpenAI Codex, GitHub Copilot, Cursor und Gemini CLI unterstützen heute dasselbe Format. Das ist das Schöne daran: Sie schreiben einmal einen Skill und können ihn über verschiedene Agenten hinweg wiederverwenden.

Warum sind Agent Skills besser als ein großer System Prompt?

Das Zauberwort lautet „Progressive Disclosure“. Die Idee ist einfach: Geben Sie dem Agenten nur die Informationen, die er gerade benötigt, und nicht alles auf einmal. Agent Skills funktionieren in drei Ebenen:

1. Metadaten (ca. 100 Token). Beim Start lädt der Agent nur den Namen und die Beschreibung jedes installierten Skills. Das ist wie das Inhaltsverzeichnis eines Buches.
2. Anweisungen. Wenn eine Aufgabe mit der Beschreibung übereinstimmt, liest der Agent den vollständigen SKILL.md-Text. Das ist, als würde man ein Kapitel öffnen.
3. Ressourcen. Skripte und Referenzdateien werden nur dann geladen, wenn der Agent sie wirklich benötigt. Dies ist wie der Anhang am Ende des Buches.

Vergleichen Sie dies nun mit einem System Prompt, der jede Anweisung für jede mögliche Aufgabe enthält. Das Kontextfenster ist begrenzt und jeder Token kostet Geld und Aufmerksamkeit. Schlimmer noch: Anweisungen, die für die aktuelle Aufgabe nicht relevant sind, lenken das Modell ab und verschlechtern die Ergebnisse. Mit Skills kostet ein großes Referenzdokument bis zum Öffnen durch den Agenten nichts.

Wie ist ein Skill aufgebaut?

Die Struktur von Agent Skills sind in der offenen Spezifikation definiert und sehr klein. Ein Skill ist ein Verzeichnis, das mindestens eine SKILL.md-Datei enthält:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: extra documentation
└── assets/           # Optional: templates and resources

Das Frontmatter von SKILL.md hat nur zwei Pflichtfelder:

• Name: Maximal 64 Zeichen. Nur Kleinbuchstaben, Zahlen und Bindestriche. Es muss mit dem Ordnernamen übereinstimmen.
• Beschreibung: Maximal 1024 Zeichen. Es sollte beschreiben, was der Skill tut und wann der Agent ihn verwenden sollte.

Es gibt auch einige optionale Felder wie license, compatibility und metadata. Der Text unter der Titelseite ist reines Markdown ohne Formatbeschränkungen. Die Spezifikation empfiehlt, SKILL.md unter 500 Zeilen zu belassen und lange Details in separate Referenzdateien zu verschieben.

Hinweis: Die Beschreibung ist die wichtigste Zeile des gesamten Skill. Der Agent entscheidet nur anhand dieses Textes, ob der Skill für die aktuelle Aufgabe relevant ist. Eine Beschreibung wie „Hilft bei PDFs“ ist zu vage. Schreiben Sie, was der Skill tut und wann er verwendet werden soll, und geben Sie die Schlüsselwörter an, die ein Benutzer sagen würde.

Wie kann ich mein erstes Skill bauen?

Lassen Sie uns ein kleines, aber nützliches Beispiel erstellen: einen Skill, der rohe Besprechungsnotizen in saubere Besprechungsprotokolle umwandelt. Sie benötigen für Agent Skills kein Framework, lediglich einen Texteditor. Ich verwende hier Claude Code, aber der gleiche Ordner funktioniert in jedem Tool, der den Standard unterstützt.

1. Erstellen Sie den Ordner Skill. In Claude Code befindet sich das persönliche Skills in ~/.claude/skills und das Projekt Skills in .claude/skills im Repository. Erstellen Sie einen Ordner mit dem Namen Ihr Skill:

mkdir -p ~/.claude/skills/meeting-minutes

2. Erstellen Sie die Datei SKILL.md. Fügen Sie die Frontmatter mit name und description hinzu und schreiben Sie die Anweisungen in den Hauptteil:

---
name: meeting-minutes
description: Turns raw meeting notes into clean, structured meeting
  minutes. Use when the user asks to summarize a meeting, write
  minutes, or clean up meeting notes.
---

# Meeting Minutes

Follow these steps to create the minutes:

1. Read the raw notes the user provides.
2. Extract the date, the participants, and the topic.
3. Group the content into: Decisions, Open Points, Action Items.
4. Every action item needs an owner and a due date. Ask the user
   if one is missing.
5. Use the template in references/template.md for the output.

3. Fügen Sie eine Referenzdatei hinzu (optional). Erstellen Sie references/template.md mit Ihrer Ausgabevorlage. Der Agent lädt diese Datei erst dann, wenn er wirklich das Protokoll erstellt. Dadurch bleibt der Hauptteil Skill schlank.
4. Testen Sie Skill. Starten Sie eine neue Agentensitzung und geben Sie ihr eine passende Aufgabe, zum Beispiel: „Können Sie diese Notizen in Besprechungsprotokolle umwandeln?“. Der Agent sieht die Beschreibung, aktiviert den Skill und folgt Ihren Anweisungen. Wenn Skill nicht ausgelöst wird, schärfen Sie die Beschreibung mit konkreteren Schlüsselwörtern.
5. Validieren Sie Skill (optional). Das Spezifikationsprojekt stellt eine kleine Referenz Tool bereit, die den Frontmater und die Benennungsregeln überprüft:

skills-ref validate ./meeting-minutes

Das ist alles. Ihr erster Skill ist fertig. Von hier aus können Sie es erweitern: Fügen Sie scripts/ ein Skript für einen Schritt hinzu, der als Code ausgeführt werden soll, oder teilen Sie lange Anweisungen in mehrere Referenzdateien auf.

Tipp: Klein anfangen. Ein Skill sollte einen Job lösen. Wenn Ihr SKILL.md immer größer wird, ist das normalerweise ein Zeichen dafür, dass Sie es in zwei Skills aufteilen oder Inhalte in den Referenzordner verschieben sollten.

Wo passt Skills neben MCP und CLI Tools?

Ich habe bereits darüber geschrieben, warum CLI Tools MCP bei KI-Agenten übertrifft. Das Hauptargument war die Kontexteffizienz: MCP Tool-Definitionen verschlingen einen Großteil des Kontextfensters, bevor der Agent etwas getan hat. Für mich sind Skills der dritte Teil desselben Bildes. CLI Tools gibt dem Agenten Fähigkeiten. MCP verbindet den Agenten mit Live-Diensten. Agent Skills bündeln das Wissen und die Arbeitsabläufe: wie Ihr Team Dinge erledigt, welche Konventionen gelten, welche Schritte zu befolgen sind. Wenn Sie die vollständige Karte dieser Bausteine ​​wünschen, stelle ich sie in meinem Beitrag über die AI Tooling-Oberfläche im Jahr 2026 zusammen.

In diesem Blogbeitrag habe ich erklärt, was Agent Skills sind, warum progressive Offenlegung einen riesigen System Prompt schlägt und wie Sie Ihren ersten Skill mit einer einfachen SKILL.md-Datei erstellen. Da das Format jetzt ein offener Standard ist, wird der Skill, den Sie heute geschrieben haben, höchstwahrscheinlich noch in den Tools funktionieren, das Sie morgen verwenden. Ein guter nächster Schritt ist die offizielle Agent Skills-Dokumentation von Anthropic und die Spezifikation selbst. Ich hoffe, das ist eine kleine Hilfe.

Bleibt gesund, Grüße Jannik