Was sind Agent-Skills wirklich? Erklärung mit MCP

Was ein Agent-Skill tatsächlich ist

Ein Agent-Skill ist ein Verzeichnis auf dem Datenträger 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. Fast alles Weitere an Skills ergibt sich aus diesen beiden Sätzen.

Das Verzeichnis kann mehr als nur diese eine Datei enthalten. Die Agent Skills-Spezifikation 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 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. Deshalb muss sie angeben, was der Skill tut und wann er verwendet werden soll – mit den Worten, die eine Person tatsächlich eingeben würde.

Warum eine Skill fast nichts kostet, bis sie 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 dieses Verfahren Progressive Disclosure.

Beim Start lädt der Agent nur name und description jeder installierten Skill. Alles andere bleibt zunächst unberücksichtigt. Die Spezifikation von Agent Skills beziffert das auf ungefähr 100 Tokens pro Skill (veröffentlichte Richtlinie, Stand August 2026). Wenn Sie ein Dutzend Skills installieren, entspricht das ungefähr dem Kontext eines langen Absatzes.

Wenn eine Anfrage zur Beschreibung einer Skill passt, liest der Agent den Inhalt dieser einen SKILL.md. Die Spezifikation empfiehlt, den Inhalt auf unter 5.000 Tokens und die Datei auf unter 500 Zeilen zu begrenzen. Dateien in references/ und scripts/ verursachen zu diesem Zeitpunkt noch 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 nicht in das Kontextfenster. Nur die Ausgabe wird dort aufgenommen.

Vergleichen Sie das mit dem, worauf viele zuerst zurückgreifen: einem einzigen riesigen Prompt. Jede Zeile in einem System-Prompt oder einer ständig geladenen Anweisungsdatei wird bei jeder Anfrage und in jeder Sitzung erneut berücksichtigt, unabhängig davon, ob die Aufgabe sie benötigt. Gleichzeitig konkurriert sie mit der eigentlichen Frage um die Aufmerksamkeit des Agenten. 10.000 Tokens dauerhaft geladener Anweisungen sind Kosten, die Sie sogar für die Frage bezahlen, wie spät es ist. Ein Dutzend Skills benötigt im Ruhezustand ungefähr 1.200 Tokens und wächst nur für die Aufgabe, die sie tatsächlich benötigt. Das ist der entscheidende Vorteil von Skills. Deshalb ist eine kleine Bibliothek besser als ein längerer Prompt.

Ein Punkt wird häufig übersehen. Sobald eine Skill geladen wurde, bleibt ihr Inhalt für den Rest der Sitzung im Kontext. Ein langer SKILL.md verursacht daher wiederkehrende Kosten und nicht nur einmalige. Details in references/ zu verschieben, dient nicht lediglich der Übersichtlichkeit. Es ist der vorgesehene Mechanismus.

Ein Agent-Skill ist kein Tool-Aufruf

Ein Tool, auch Funktionsaufruf genannt, kann vom Modell aufgerufen werden. Der Harness stellt dem Modell ein Schema bereit: einen Namen, eine Beschreibung und die Struktur der Argumente. Das Modell gibt einen Aufruf aus, Ihr Code führt ihn aus, und das Ergebnis wird als Nachricht zurückgegeben. Tools führen Aktionen aus. Beide Seiten dieses Austauschs gehören zum Harness, also zum Programm, das die Schleife um das Modell ausführt. Dieses Programm liest beim Start auch Ihre Skill-Beschreibungen und entscheidet, wann ein Skill geöffnet wird.

Ein Skill führt selbst nichts aus. Der Agent liest ihn und arbeitet dann mit den Tools, die ihm bereits zur Verfügung stehen. Das Modell kann einem Skill nicht auf dieselbe Weise Argumente übergeben wie einem Tool. Ein Skill kann dem Modell jedoch vorgeben, 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 deutlichste Beispiel: eine Claude-Code-Sitzung kann bereits eine andere Sitzung Nachrichten senden, und im Skill wird festgelegt, wann das sinnvoll ist und welche Informationen übermittelt werden sollen.

Kurz gesagt: Ein Tool gibt einem Agenten eine neue Fähigkeit, während ein Skill ihm vermittelt, wie er eine bereits vorhandene Fähigkeit beurteilt und einsetzt. Wenn ein Schritt jedes Mal ein exakt validiertes Ergebnis liefern muss, benötigen Sie ein Tool oder ein Skript. Wenn ein Schritt erfordert, dass dieselbe Überlegung konsequent angewendet wird, benötigen Sie einen Skill. Ein Skill kann ausschließlich aus Beurteilungen bestehen und trotzdem der Skill sein, den Sie am häufigsten verwenden, 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 einsetzt. Diese Beurteilung kann auch in die andere Richtung weisen. Der unlazy-Skill, der einen Depth Tree durchläuft, damit ein Agent einen Auftrag nicht vorzeitig für abgeschlossen erklärt, verwendet dasselbe Prinzip mit dem Ziel, gründlicher statt zurückhaltender zu arbeiten.

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 dieses Protokoll verwendet und dem Agenten Tools bereitstellt. Dafür benötigt er normalerweise eine Konfiguration, Zugangsdaten sowie entweder einen lokalen Befehl oder einen Netzwerkendpunkt. Ein Skill ist ein Ordner mit einer Markdown-Datei. Es gibt keinen Prozess, keinen Port und kein Protokoll.

Auch die Kosten für den Kontext unterscheiden sich entsprechend. Jedes Tool, das ein MCP-Server bereitstellt, verfügt über einen Namen, eine Beschreibung und ein Argument-Schema. Standardmäßig befinden sich diese Informationen für die gesamte Sitzung in der Anfrage, unabhängig davon, ob sie verwendet werden. Einige Clients rufen Tool-Schemas inzwischen bei Bedarf ab. Das vorherige Laden ist jedoch weiterhin der Normalfall. Ein gespeicherter Skill besteht aus einer Textzeile.

Beide ergänzen sich, und die leistungsfähigsten Setups verwenden beide. Der MCP-Server stellt den Zugriff bereit. Der Skill beschreibt das Verfahren: welche dieser Tools für den tatsächlichen Workflow Ihres Teams in welcher Reihenfolge aufgerufen werden und wie ein gutes Ergebnis aussieht. Wenn Sie den Server selbst hosten, behandelt MCP-Server auf einem VPS betreiben 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. Projektspezifische Skills liegen in .claude/skills/<name>/SKILL.md und werden in git versioniert, sodass jede Person und jeder Agent, die in diesem Repository arbeiten, darauf zugreifen können. GitHub Copilot und VS Code lesen Workspace-Skills stattdessen aus .github/skills/. Die darin enthaltene Datei ist identisch.

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.

Das ist ein vollständiges Skill. 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. Fehlt der Eintrag in diesem Menü, ist ein Name falsch: Die Datei muss SKILL.md heißen, und der Verzeichnisname darf nur Kleinbuchstaben, Ziffern und einzelne Bindestriche enthalten. Eine auf diese Weise als Prozedur formulierte Aufgabe, die Ihr Agent erneut ausführen kann, ergänzt geplante restic-Backups auf einem VPS sinnvoll, weil ein laufendes Backup nicht dasselbe ist wie eine Wiederherstellung aus dem Backup.

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 das das Format eines einzelnen Anbieters oder ein Standard?

Anthropic veröffentlichte das Format Ende 2025 und gab es anschließend als offenen Standard unter agentskills.io heraus. Mit Stand August 2026 definiert die 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. Damit prüft skills-ref validate ./my-skill einen Ordner anhand der Spezifikation, bevor Sie ihn weitergeben.

Die Liste der Clients ist das entscheidende Signal. 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 überwacht, wie Sie eine Aufgabe einmal ausführen, rekonstruiert daraus eine Absicht mit geordneten Schritten und schreibt das Ergebnis als Skill. Wenn ein Anbieter einen Recorder entwickelt, dessen Ausgabeformat auf der Spezifikation eines anderen Anbieters basiert, ist das ein gutes Zeichen dafür, dass das Format nicht mehr nur ein Feature eines einzelnen Produkts 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 einem Agent-Skill und einem MCP-Server?

Ein MCP-Server (Model Context Protocol) ist ein laufender Prozess, der einem Agenten über ein Protokoll Tools bereitstellt. Deshalb benötigt er Konfiguration und Zugangsdaten. Seine Tool-Definitionen belegen normalerweise während der gesamten Sitzung Kontext, unabhängig davon, ob sie verwendet werden oder nicht. Ein Agent-Skill ist ein Verzeichnis mit einer SKILL.md-Datei. Er benötigt weder einen Prozess noch ein Protokoll und kostet etwa 100 Tokens, bis der Agent entscheidet, die Datei zu lesen. Verwenden Sie einen MCP-Server, um einem Agenten Zugriff auf ein System zu geben. Verwenden Sie einen Skill, um dem Agenten das richtige Vorgehen für diesen Zugriff vorzugeben. Viele Setups 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. Dasselbe Verzeichnis wird von Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands und anderen Clients gelesen. Der Unterschied liegt 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/ im Repository. Die Datei SKILL.md selbst kann unverändert zwischen den Clients verschoben werden.

Wie viele Skills kann ich installieren, bevor das System langsamer wird?

Entscheidend ist das Startbudget, nicht eine bestimmte Anzahl. Jeder installierte Skill fügt seinen Namen und seine Beschreibung hinzu. Nach den veröffentlichten Vorgaben der Spezifikation sind das ungefähr 100 Tokens. Dreißig Skills kosten daher etwa 3.000 Tokens, bevor einer von ihnen verwendet wird. Zuerst verschlechtert sich nicht die Geschwindigkeit, sondern die Zuordnung: Viele Skills mit ähnlichen Beschreibungen erschweren es dem Modell, den richtigen auszuwählen. Formulieren Sie Beschreibungen ohne Überschneidungen und löschen Sie Skills, die Sie nicht mehr verwenden.

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

Prüfen Sie, ob sie für jede Aufgabe im Repository gilt. Build-Befehle, Vorgaben für den Schreibstil und Benennungsregeln gelten für alle Aufgaben. Sie gehören daher in die Datei, die immer geladen wird, weil genau das ihr Zweck ist. Ein Verfahren, das Sie nur gelegentlich ausführen, beispielsweise eine Release-Checkliste oder eine Restore-Übung, sollte ein Skill sein. Dadurch verursacht es bei Aufgaben, die es nicht benötigen, keine Kosten. Ein Abschnitt in AGENTS.md, der zu nummerierten Schritten angewachsen ist, ist normalerweise ein Skill, der verschoben werden sollte.