Agent Skills erklärt: SKILL.md, Aufbau und MCP

Was ein Agent-Skill tatsächlich ist

Ein Agent-Skill ist ein Verzeichnis auf der Festplatte mit einer Datei namens SKILL.md. Diese Datei enthält einen Namen, eine kurze Beschreibung und Anweisungen in einfachem Markdown. Der Agent lädt die Beschreibung beim Start. Die Anweisungen liest er nur, wenn Ihre Anfrage zu dieser Beschreibung passt oder Sie den Skill mit seinem Namen aufrufen. Fast alles andere an Skills ergibt sich aus diesen beiden Sätzen.

Das Verzeichnis kann mehr als diese eine Datei enthalten. Die Agent Skills specification nennt drei optionale Verzeichnisse: scripts/ für Code, den der Agent ausführt, references/ für Dokumente, die er bei Bedarf liest, und assets/ für Vorlagen und Daten. Keines davon ist erforderlich. Ein Verzeichnis, das nur eine SKILL.md enthält, ist bereits ein vollständiger Skill.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

Die Beschreibung wird häufig unterschätzt. Sie ist der einzige Text, den der Agent sieht, bevor er entscheidet, ob er den Skill überhaupt öffnet. Daher muss sie erklären, was der Skill tut und wann er verwendet werden soll – mit den Worten, die eine Person tatsächlich eingeben würde.

Warum ein Skill fast nichts kostet, bis er verwendet wird

Das ist das Argument, das dieses Format verständlich und lohnenswert macht. Es geht um den Kontext, nicht um Funktionen. Das Laden erfolgt in Stufen. Die Spezifikation nennt dies progressive Offenlegung.

Beim Start lädt der Agent von jedem installierten Skill nur name und description. Die Spezifikation für Agent Skills beziffert das ungefähr mit 100 Tokens pro Skill (veröffentlichte Empfehlung, Stand Oktober 2026). Wenn Sie ein Dutzend Skills installieren, entspricht das ungefähr dem Kontext eines langen Absatzes.

Wenn eine Anfrage zu einer Beschreibung passt, liest der Agent den Inhalt dieses einen SKILL.md. Die Spezifikation empfiehlt, den Inhalt auf weniger als 5.000 Tokens und die Datei auf weniger als 500 Zeilen zu beschränken. Dateien in references/ und scripts/ verursachen zu diesem Zeitpunkt weiterhin keine Kosten. Eine Referenzdatei wird erst geladen, wenn die Anweisungen den Agenten dorthin verweisen. Ein gebündeltes Skript funktioniert wiederum anders: Der Agent führt es über die Shell aus. Der Quelltext des Skripts gelangt daher nie in das Kontextfenster. Nur die Ausgabe wird dort übernommen.

Vergleichen Sie das mit dem, worauf viele zuerst zurückgreifen: einem einzigen, riesigen Prompt. Jede Zeile in einem System-Prompt oder einer dauerhaft aktiven Anweisungsdatei wird bei jeder Anfrage und in jeder Sitzung verarbeitet, unabhängig davon, ob die Aufgabe sie benötigt. Außerdem konkurriert sie mit der eigentlichen Frage um die Aufmerksamkeit des Agenten. 10.000 Tokens dauerhafter Anweisungen verursachen Kosten, selbst wenn Sie nur nach der Uhrzeit fragen. Ein Dutzend Skills benötigt im Ruhezustand ungefähr 1.200 Tokens und wird nur für die Aufgabe erweitert, die diese Informationen benötigt. Das ist der gesamte Vorteil von Skills. Deshalb ist eine kleine Bibliothek besser als ein längerer Prompt.

Ein Punkt wird häufig übersehen. Sobald ein Skill geladen ist, bleibt sein Inhalt für den Rest der Sitzung im Kontext. Ein langes SKILL.md verursacht daher wiederkehrende Kosten und nicht nur einmalige Kosten. Details nach references/ zu verschieben, dient nicht nur der Übersichtlichkeit. So funktioniert der Mechanismus bestimmungsgemäß.

Ein Agent-Skill ist kein Tool-Aufruf

Ein Tool, auch Function Call genannt, ist etwas, das das Modell aufrufen kann. Das Harness sendet dem Modell ein Schema: einen Namen, eine Beschreibung und die Struktur der Argumente. Das Modell erzeugt einen Aufruf, Ihr Code führt ihn aus, und das Ergebnis kommt als Nachricht zurück. Tools führen Aktionen aus. Beide Seiten dieses Austauschs gehören zu dem Harness, dem Programm, das die Schleife um das Modell ausführt. Dieses Programm liest beim Start auch Ihre Skill-Beschreibungen und entscheidet, wann es einen Skill öffnet.

Ein Skill führt selbst nichts aus. Der Agent liest ihn und handelt anschließend mit den Tools, die ihm bereits zur Verfügung standen. Das Modell kann keine Argumente an einen Skill übergeben, wie es Argumente an ein Tool übergibt. Ein Skill kann dem Modell jedoch mitteilen, welche Tools es in welcher Reihenfolge verwenden und was es anschließend prüfen soll. Einen Auftrag an einen zweiten Agenten zu übergeben, ist das klarste Beispiel: Eine Claude Code-Sitzung kann bereits einer anderen Nachrichten senden, und im Skill legen Sie fest, wann sich das lohnt und was gesendet werden soll.

Kurz gesagt: Ein Tool verleiht einem Agenten eine neue Fähigkeit, während ein Skill ihm vor allem Urteilsvermögen für bereits vorhandene Fähigkeiten vermittelt. Wenn ein Skill eine Fähigkeit hinzufügt, geschieht das über ein mitgeliefertes Script, das der Agent mit der bereits vorhandenen Shell ausführt. Muss ein Schritt jedes Mal ein exaktes, validiertes Ergebnis erzeugen, benötigen Sie ein Tool oder ein Script. Erfordert ein Schritt, dass dieselbe Überlegung konsequent angewendet wird, benötigen Sie einen Skill. Ein Skill kann ausschließlich aus Urteilsvermögen bestehen und trotzdem derjenige sein, zu dem Sie am häufigsten greifen, wie Ponytail zeigt, das einen Coding-Agenten dazu bringt, die kleinste funktionierende Änderung vorzunehmen: Es fügt keine neue Fähigkeit hinzu, sondern ändert nur, wie der Agent die bereits vorhandenen Fähigkeiten nutzt. Dieses Urteilsvermögen kann auch in die andere Richtung weisen. Der unlazy-Skill, der einen Depth Tree durchläuft, damit ein Agent einen Auftrag nicht vorzeitig als abgeschlossen erklärt, wendet denselben Ansatz auf Gründlichkeit statt Zurückhaltung an.

Ein Agent-Skill ist kein MCP-Server

MCP (Model Context Protocol) ist ein Protokoll, über das ein Agent mit einem externen System verbunden wird. Ein MCP-Server ist ein Prozess, der ausgeführt wird, dieses Protokoll spricht und dem Agenten Tools bereitstellt. Dafür sind normalerweise eine Konfiguration, Zugangsdaten und entweder ein lokaler Befehl oder ein Netzwerkendpunkt erforderlich. Ein Skill ist ein Ordner mit einer Markdown-Datei. Es gibt keinen Prozess, keinen Port und kein Protokoll.

Die Kosten für den Kontext unterscheiden sich auf dieselbe Weise. Jedes Tool, das ein MCP-Server bereitstellt, enthält einen Namen, eine Beschreibung und ein Argument-Schema. Bei einem Client, der diese Informationen vorab lädt, befinden sie sich während der gesamten Sitzung in der Anfrage, unabhängig davon, ob sie verwendet werden. Claude Code arbeitet standardmäßig nicht mehr so: Seit October 2026 ist die Toolsuche standardmäßig aktiviert. Zu Beginn der Sitzung werden daher nur Toolnamen und Serveranweisungen geladen. Die vollständigen Definitionen werden geladen, wenn Claude danach sucht. Ein Skill benötigt im Ruhezustand eine Textzeile.

Beide ergänzen sich, und die leistungsfähigsten Setups verwenden beide. Der MCP-Server stellt den Zugriff bereit. Der Skill beschreibt das Vorgehen: Welche dieser Tools für den tatsächlichen Workflow Ihres Teams aufgerufen werden, in welcher Reihenfolge und woran ein gutes Ergebnis zu erkennen ist. Wenn Sie den Server selbst betreiben, behandelt MCP-Server auf einem VPS ausführen diesen Teil.

Eine Agent-Skill ist kein System-Prompt und keine AGENTS.md

Beides sind Anweisungen in Markdown, daher ist diese Verwechslung nachvollziehbar. Der Unterschied liegt darin, wann sie geladen werden. AGENTS.md, CLAUDE.md und die Systemaufforderung sind immer aktiv. Ein Skill wird nur bei Bedarf aktiviert. Claudes Ausgabestile stehen am äußersten Ende von „immer aktiv“, weil die Auswahl eines Stils die Systemaufforderung selbst bearbeitet. Dadurch wird jede Antwort in der Sitzung beeinflusst, auch Antworten, die von keinem Skill verarbeitet werden.

Die Prüfung besteht aus einer Frage: Wäre es bei einer Aufgabe ohne Bezug zu diesem Absatz falsch, ihn zu ignorieren? Der Hausstil, der Build-Befehl und die Regel für die Benennung von Branches gelten für jede Aufgabe. Daher gehören sie in die Datei, die immer aktiv ist. Genau dafür wird sie bei jedem Durchlauf geladen. Die Release-Checkliste, die Sie zweimal im Monat ausführen, gilt nicht für jede Aufgabe. Daher gehört sie in eine Skill. Wenn ein Abschnitt Ihrer immer aktiven Datei zu einer nummerierten Vorgehensweise angewachsen ist, ist das ein Hinweis darauf, dass Sie ihn in eine Skill verschieben sollten.

Für diese Dateien gelten eigene Konventionen, die Sie korrekt umsetzen sollten. Siehe was in AGENTS.md und was in die Datei für Menschen gehört sowie eine design.md, die den Aufbau einer Codebasis erklärt, die beiden von uns verwendeten Dateien.

Wie ein minimales Skill aussieht

In Claude Code liegen persönliche Skills in ~/.claude/skills/<name>/SKILL.md und gelten für alle Ihre Projekte. Projekt-Skills liegen in .claude/skills/<name>/SKILL.md und werden in Git versioniert. Dadurch stehen sie allen Personen und allen Agents zur Verfügung, die in diesem Repository arbeiten. GitHub Copilot und VS Code lesen Projekt-Skills aus .github/skills/ und .agents/skills/ sowie aus .claude/skills/. Die darin enthaltene Datei ist dieselbe Datei.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Damit ist das Skill vollständig. Der Verzeichnisname wird zum Befehl, den Sie eingeben. In diesem Fall lautet er /restore-drill. In Claude Code zeigt das Menü /skills an, welche Skills installiert sind. Das ist die schnellste Möglichkeit zu prüfen, ob die Datei erkannt wurde. Wenn sie in diesem Menü fehlt, prüfen Sie zuerst die Namen: Die Datei muss SKILL.md heißen. Die Agent Skills-Spezifikation verlangt außerdem, dass der Name aus Kleinbuchstaben, Ziffern und einzelnen Bindestrichen besteht und mit dem Verzeichnisnamen übereinstimmt. Dasselbe Vorgehen als Prozedur, die Ihr Agent erneut ausführen kann, ergänzt sich gut mit geplanten restic-Backups auf einem VPS, weil ein laufendes Backup nicht dasselbe ist wie eine erfolgreiche Wiederherstellung.

Wann eine Fertigkeit ein Skript sein sollte

Jeder Schritt mit bei jedem Durchlauf genau einem korrekten Ergebnis sollte ein Skript sein. Die Fertigkeit wird dann auf wenige Zeilen reduziert, die angeben, wann das Skript ausgeführt wird und wie die Ausgabe zu lesen ist. Dafür gibt es zwei Gründe. Beide sind praktisch relevant.

Erstens gelangt der Quelltext eines Skripts nie in das Kontextfenster. Ein Parser mit 300 Zeilen kostet nur seine Ausgabe. Dieselbe Logik als Markdown-Anleitung kostet dagegen bei jedem Laden der Fertigkeit ihre vollständige Länge.

Zweitens liefert ein Skript zweimal dasselbe Ergebnis. Ein Modell, das bei jedem Durchlauf dieselbe Regel zum Parsen von Logs neu ableiten soll, erzeugt sie an einem schlechten Tag leicht unterschiedlich. Sie bemerken das möglicherweise erst, wenn zwei Zahlen nicht übereinstimmen.

Teilen Sie die Arbeit daher nach ihrer Art auf. „Die CSV-Datei parsen und jede Zeile ausgeben, deren Gesamtsumme nicht mit den Einzelposten übereinstimmt“ ist ein Skript. „Die vom Skript ausgegebenen Zeilen prüfen und erklären, welche davon nach einem Fehler bei der Dateneingabe aussehen“ ist eine Anweisung für eine Fertigkeit. Behalten Sie die Beurteilung in Markdown und die deterministischen Schritte im Code. Das ist dieselbe Disziplin wie beim Erstellen einer Schleife, die ein Agent ohne Ihre Überwachung ausführen kann.

Warum wird mein Skill nie ausgelöst?

Weil in description steht, was der Skill tut, aber nie, wann er verwendet werden soll. Diese eine Zeile muss der Agent mit Ihrer Anfrage abgleichen. „Unterstützt bei Datenbankaufgaben“ passt zu nichts Bestimmtem. „Führt eine Schema-Migration in der Staging-Datenbank aus. Verwenden, wenn der Benutzer eine Tabelle migrieren, eine Spalte hinzufügen oder ein Schema ändern möchte“ enthält die Wörter, die eine Person tatsächlich eingibt. Dadurch wird der Skill ausgelöst.

Der umgekehrte Fehler ist ein Skill, der ständig ausgelöst wird. Eine Beschreibung wie „Für alle Codeänderungen in diesem Repository verwenden“ passt auf alles. Dadurch wird der Inhalt bei jeder Aufgabe geladen und bleibt anschließend für den Rest der Sitzung im Kontext. Formulieren Sie die Beschreibung so, dass sie nur auf den vorgesehenen Fall zutrifft. In Claude Code können Sie außerdem disable-model-invocation: true im Frontmatter setzen. Dadurch wird das automatische Laden deaktiviert. Der Skill bleibt verfügbar, wenn Sie seinen Namen eingeben.

Der dritte Fehler ist ein Skill, der ein Tool dupliziert. Anweisungen, die den Agenten auffordern, eine API über curl aufzurufen, die der MCP-Server bereits bereitstellt, oder Dateien mit grep zu durchsuchen, obwohl das Harness ein Suchtool hat, erzeugen einen langsameren Ablauf und zwei Anweisungssätze, die sich widersprechen können. Entfernen Sie das Duplikat und beschreiben Sie stattdessen die Absicht.

Raten Sie nicht, welcher dieser drei Fälle vorliegt. Führen Sie denselben Prompt zweimal in einer neuen Sitzung aus: einmal mit verfügbarem Skill und einmal mit deaktiviertem Skill. Vergleichen Sie anschließend die Antworten. Die neue Sitzung ist wichtig, weil die Sitzung, in der Sie den Skill geschrieben haben, bereits alle darin enthaltenen Informationen kennt. Dadurch bleiben Lücken in der geschriebenen Version verborgen. Das Plugin skill-creator von Anthropic automatisiert diesen Vergleich innerhalb von Claude Code. Es generiert auch Prompts, die den Skill auslösen sollen beziehungsweise nicht auslösen sollen, und misst, wie häufig dies jeweils geschieht. Wenn der Skill geladen wird und der Agent trotzdem nicht tut, was darin steht, liegt das Problem nicht an der Beschreibung. Prüfen Sie als Nächstes die Gründe, aus denen ein Agent Anweisungen ignoriert, die er bereits gelesen hat.

Ist dies das Format eines einzelnen Anbieters oder ein Standard?

Anthropic veröffentlichte das Format Ende 2025 und stellte es anschließend als offenen Standard unter agentskills.io bereit. Im Oktober 2026 definiert diese Spezifikation die erforderlichen Felder name und description, die optionalen Felder license, compatibility, metadata und allowed-tools, die drei optionalen Verzeichnisse sowie das stufenweise Laden. Außerdem enthält sie einen Referenz-Validator. Mit skills-ref validate ./my-skill können Sie daher einen Ordner vor der Freigabe gegen die Spezifikation prüfen.

Die Liste der Clients ist der entscheidende Hinweis. Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands und opencode lesen unter anderem denselben Ordner. Microsoft veröffentlicht eigene Skills in diesem Format unter github.com/microsoft/skills und bietet ein Desktop-Tool namens Skill Recorder an. Dieses Tool zeichnet auf, wie Sie eine Aufgabe einmal ausführen, rekonstruiert daraus eine Absicht mit geordneten Schritten und schreibt das Ergebnis als Skill. Wenn ein Anbieter ein Aufzeichnungsprogramm entwickelt, dessen Ausgabeformat auf der Spezifikation eines anderen Anbieters basiert, ist das ein gutes Zeichen dafür, dass das Format keine Funktion eines einzelnen Produkts mehr ist.

Zuerst schreiben

Planen Sie keine Bibliothek. Warten Sie, bis Sie feststellen, dass Sie dieselben Anweisungen zum dritten Mal in einen Chat kopieren. Verschieben Sie den Text dann in eine SKILL.md und löschen Sie die Kopie. Eine bereits spürbare Wiederholung ist der einzige zuverlässige Auslöser für eine Fähigkeit, die sich zu bewahren lohnt. Ein Suchverfahren ist ein guter Anfang. Eine Suchfähigkeit mit eigener SearXNG-Instanz zeigt, wie das aussehen kann.

Zwei Gewohnheiten halten die Bibliothek gepflegt. Lesen Sie jede Fähigkeit, die Sie nicht selbst geschrieben haben, einschließlich der Skripte, bevor Sie sie installieren. Eine Fähigkeit enthält Anweisungen, die Ihr Agent befolgt, und möglicherweise Code, den er ausführt. Behandeln Sie sie daher wie die Installation von Software aus einer unbekannten Quelle. Halten Sie außerdem Zugangsdaten aus dem Ordner heraus, weil eine Fähigkeit eine Textdatei ist, die versioniert und weitergegeben wird. Geheimnisse von Ihren Agents fernhalten beschreibt, wo diese Werte stattdessen hingehören. Der Fahrplan zum Lernen von Agents in diesem Jahr ordnet Fähigkeiten zusammen mit den übrigen Einrichtungsschritten ein.

FAQ

Was ist der Unterschied zwischen einer Agent-Skill und einem MCP-Server?

Ein MCP-Server (Model Context Protocol) ist ein laufender Prozess, der einem Agenten über ein Protokoll Tools bereitstellt. Daher benötigt er Konfiguration und Zugangsdaten. Die vollständigen Tool-Definitionen belegen während der gesamten Sitzung Kontext, sofern der Client sie nicht verzögert, wie es Claude Code inzwischen standardmäßig tut. Eine Agent-Skill ist ein Ordner mit einer SKILL.md-Datei. Sie benötigt weder einen Prozess noch ein Protokoll und belegt etwa 100 Tokens, bis der Agent entscheidet, sie zu lesen. Verwenden Sie einen MCP-Server, um einem Agenten Zugriff auf ein System zu geben. Verwenden Sie eine Skill, um dem Agenten das richtige Vorgehen für diesen Zugriff vorzugeben. Viele Umgebungen verwenden beides.

Funktionieren Agent-Skills nur mit Claude Code?

Nein. Anthropic hat das Format entwickelt und anschließend als offenen Standard unter agentskills.io veröffentlicht. Daher wird derselbe Ordner von Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands und anderen Clients gelesen. Unterschiede bestehen darin, wo die einzelnen Clients suchen und welche zusätzlichen Frontmatter-Felder sie verstehen. Claude Code liest ~/.claude/skills/ und .claude/skills/. GitHub Copilot und VS Code lesen .github/skills/, .claude/skills/ oder .agents/skills/ im Repository. Die SKILL.md-Datei selbst kann unverändert zwischen diesen Clients verschoben werden.

Wie viele Skills kann ich installieren, bevor die Verarbeitung langsamer wird?

Entscheidend ist das Startbudget, nicht die Anzahl. Jede installierte Skill fügt ihren Namen und ihre Beschreibung hinzu. Nach den veröffentlichten Vorgaben der Spezifikation sind das ungefähr 100 Tokens. Dreißig Skills belegen daher etwa 3.000 Tokens, bevor eine davon verwendet wird. Zuerst verschlechtert sich die Zuordnung, nicht die Geschwindigkeit: Viele Skills mit ähnlichen Beschreibungen erschweren es dem Modell, die richtige auszuwählen. Schreiben Sie Beschreibungen ohne Überschneidungen und löschen Sie Skills, die Sie nicht mehr verwenden.

Sollte diese Anweisung in eine Skill oder in AGENTS.md?

Prüfen Sie, ob sie für jede Aufgabe im Repository gilt. Build-Befehle, der projektspezifische Stil und Benennungsregeln gelten für alle Aufgaben. Sie gehören daher in die Datei, die immer geladen wird. Genau dafür wird sie bei jedem Vorgang geladen. Ein Verfahren, das Sie nur gelegentlich ausführen, beispielsweise eine Release-Checkliste oder eine Restore-Übung, sollte eine Skill sein. Bei Aufgaben, die es nicht benötigen, kostet sie dann nur ihre einzeilige Beschreibung. Ein Abschnitt von AGENTS.md, der zu nummerierten Schritten angewachsen ist, ist in der Regel eine Skill, die verschoben werden sollte.