Was ist ein Agent-Skill wirklich?

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 erst, wenn Ihre Anfrage zu dieser Beschreibung passt. Fast alles andere an Skills ergibt sich aus diesen beiden Sätzen.

Das Verzeichnis kann mehr als 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, und zwar 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 das Format verständlich und sinnvoll macht. Es geht um den Kontext, nicht um Funktionen. Das Laden erfolgt in mehreren Stufen. Die Spezifikation nennt das progressive Offenlegung.

Beim Start lädt der Agent von jedem installierten Skill nur name und description. Die Agent-Skills-Spezifikation veranschlagt dafür ungefähr 100 Tokens pro Skill (veröffentlichte Vorgabe, Stand August 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 begrenzen. 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 mitgeliefertes Skript funktioniert nochmals 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, sehr großen Prompt. Jede Zeile in einem System-Prompt oder einer ständig geladenen Anweisungsdatei wird bei jeder Anfrage und in jeder Sitzung berücksichtigt, unabhängig davon, ob die Aufgabe sie benötigt. Gleichzeitig konkurriert sie mit der eigentlichen Frage um die Aufmerksamkeit des Modells. 10.000 Tokens an dauerhaft geltenden 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 den jeweiligen Skill benötigt. Das ist die gesamte Begründung für Skills. Deshalb ist eine kleine Bibliothek besser als ein längerer Prompt.

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

Eine Agentenfähigkeit ist kein Tool-Aufruf

Ein Tool, auch als Funktionsaufruf bezeichnet, 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 wird als Nachricht zurückgesendet. Tools führen Aktionen aus.

Eine Fähigkeit führt selbst nichts aus. Der Agent liest sie und handelt anschließend mit den Tools, die ihm bereits zur Verfügung stehen. Das Modell kann einer Fähigkeit keine Argumente übergeben, wie es Argumente an ein Tool übergibt. Eine Fähigkeit kann dem Modell vorgeben, welche Tools es in welcher Reihenfolge verwenden und was es anschließend prüfen soll.

Kurz gesagt: Ein Tool gibt einem Agenten eine neue Fähigkeit, während eine Agentenfähigkeit ihm ein Urteil über eine bereits vorhandene Fähigkeit vermittelt. Wenn ein Schritt jedes Mal ein exaktes, validiertes Ergebnis liefern muss, benötigen Sie ein Tool oder ein Skript. Wenn ein Schritt erfordert, dass dieselbe Überlegung konsistent angewendet wird, benötigen Sie eine Agentenfähigkeit.

Eine Agent-Fähigkeit 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. Er benötigt normalerweise eine Konfiguration, Zugangsdaten sowie entweder einen lokalen Befehl oder einen Netzwerkendpunkt. Eine Fähigkeit ist ein Ordner mit einer Markdown-Datei. Es gibt keinen Prozess, keinen Port und kein Protokoll.

Die Kontextkosten unterscheiden sich entsprechend. Jedes Tool, das ein MCP-Server bereitstellt, enthält einen Namen, eine Beschreibung und ein Argument-Schema. Standardmäßig werden diese für die gesamte Sitzung in die Anfrage aufgenommen, unabhängig davon, ob sie verwendet werden. Einige Clients rufen Tool-Schemas inzwischen bei Bedarf ab. Das vorherige Laden ist jedoch weiterhin der Normalfall. Eine gespeicherte Fähigkeit besteht aus einer Textzeile.

Beide ergänzen sich. Die leistungsfähigsten Setups verwenden beide. Der MCP-Server stellt den Zugriff bereit. Die Fähigkeit beschreibt das Vorgehen: Welche dieser Tools im realen Workflow Ihres Teams aufgerufen werden, in welcher Reihenfolge und woran ein gutes Ergebnis erkennbar ist. Wenn Sie eigene MCP-Server betreiben, behandelt MCP-Server auf einem VPS betreiben diesen Teil.

Die Fähigkeit eines Agents ist weder eine Systemaufforderung noch eine AGENTS.md-Datei

Beides sind Anweisungen in Markdown, daher ist diese Verwechslung nachvollziehbar. AGENTS.md, CLAUDE.md und die Systemaufforderung sind immer aktiv. Eine Fähigkeit wird bei Bedarf aktiviert.

Die entscheidende Frage lautet: Wäre es bei einer Aufgabe, die damit nichts zu tun hat, falsch, diesen Absatz zu ignorieren? Hausstil, Build-Befehl und Regel für die Benennung von Branches gelten für jede Aufgabe. Sie gehören daher in die Datei, die immer geladen wird. Genau dafür wird sie bei jeder Aufgabe geladen. Die Release-Checkliste, die Sie zweimal pro Monat ausführen, gilt nicht für jede Aufgabe. Sie gehört daher in eine Fähigkeit. Wenn ein Abschnitt Ihrer immer aktiven Datei zu einer nummerierten Prozedur angewachsen ist, ist das ein Zeichen dafür, dass Sie ihn 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, für die beiden Varianten, die wir verwenden.

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, 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.

Damit ist das Skill vollständig. Der Verzeichnisname wird zum Befehl, den Sie eingeben. Dieses Skill heißt daher /restore-drill. In Claude Code zeigt das Menü /skills die installierten Skills an. Damit können Sie am schnellsten prüfen, ob die Datei erkannt wurde. Fehlt es in diesem Menü, stimmt ein Name nicht: Die Datei muss SKILL.md heißen, und der Verzeichnisname darf nur Kleinbuchstaben, Ziffern und einzelne Bindestriche enthalten. Dasselbe Vorgehen als Prozedur, die Ihr Agent erneut ausführen kann, ergänzt sich sinnvoll mit geplanten restic-Backups auf einem VPS. Dabei ist ein erfolgreich ausgeführtes Backup nicht dasselbe wie eine erfolgreiche Wiederherstellung.

Wann ein Skill stattdessen ein Script sein sollte

Jeder Schritt mit bei jedem Durchlauf genau einem korrekten Ergebnis sollte als Script umgesetzt werden. Der Skill wird dann auf wenige Zeilen reduziert, die angeben, wann das Script ausgeführt werden soll und wie die Ausgabe zu lesen ist. Dafür gibt es zwei praktische Gründe.

Erstens gelangt der Quellcode eines Scripts nie in das Kontextfenster. Ein Parser mit 300 Zeilen belastet den Kontext nur mit seiner Ausgabe. Dieselbe Logik als Markdown-Anleitung geschrieben belastet ihn dagegen jedes Mal mit dem vollständigen Text, wenn der Skill geladen wird.

Zweitens liefert ein Script zweimal dasselbe Ergebnis. Ein Modell, das bei jedem Durchlauf dieselbe Regel zum Parsen von Logs erneut herleiten soll, kommt an einem schlechten Tag zu leicht unterschiedlichen Ergebnissen. Das fällt erst auf, wenn zwei Zahlen nicht übereinstimmen.

Teilen Sie die Arbeit daher nach ihrer Art auf. „Die CSV-Datei parsen und jede Zeile ausgeben, deren Summe nicht mit den Einzelpositionen übereinstimmt“ ist ein Script. „Die vom Script ausgegebenen Zeilen prüfen und erklären, welche davon wie ein Erfassungsfehler aussehen“ ist eine Skill-Anweisung. Beurteilungen in Markdown und deterministische Abläufe im Code zu halten, folgt derselben Disziplin wie einen Loop zu erstellen, den ein Agent ohne Ihre Überwachung ausführen kann.

Warum wird mein Skill nie ausgelöst?

Weil sein description beschreibt, was der Skill tut, aber nie angibt, wann er verwendet werden soll. Diese eine Zeile muss der Agent mit Ihrer Anfrage abgleichen. „Hilft bei Datenbankarbeiten“ passt zu keiner konkreten Anfrage. „Führt eine Schema-Migration gegen die 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 ein Benutzer 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. Grenzen Sie die Beschreibung auf den vorgesehenen Anwendungsfall ein. In Claude Code können Sie außerdem disable-model-invocation: true im Frontmatter setzen. Dadurch wird das automatische Laden verhindert, und der Skill bleibt verfügbar, wenn Sie seinen Namen eingeben.

Der dritte Fehler ist ein Skill, der ein Tool dupliziert. Anweisungen, die den Agent anweisen, eine API zu curl, die der MCP-Server bereits bereitstellt, oder Dateien zu durchsuchen, obwohl der Harness ein Such-Tool besitzt, führen zu einem langsameren Ablauf. Außerdem entstehen 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. Die Sitzung, in der Sie den Skill geschrieben haben, enthält bereits alles, was der Skill beschreibt. Dadurch werden Lücken in der geschriebenen Version verdeckt. Das skill-creator-Plugin von Anthropic automatisiert diesen Vergleich in Claude Code. Es erzeugt auch Prompts, die den Skill auslösen sollen oder nicht auslösen sollen, und misst, wie häufig dies jeweils geschieht.

Ist dieses Format an einen Anbieter gebunden oder ein Standard?

Anthropic veröffentlichte das Format Ende 2025 und stellte es anschließend als offenen Standard unter agentskills.io bereit. 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 wird ein Referenz-Validator bereitgestellt. Mit skills-ref validate ./my-skill prüfen Sie einen Ordner vor der Weitergabe gegen die Spezifikation.

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 Tool zeichnet einmalig auf, wie Sie eine Aufgabe ausführen, rekonstruiert daraus eine Absicht mit geordneten Schritten und schreibt das Ergebnis als Skill. Wenn ein Anbieter ein Aufzeichnungsprogramm entwickelt, dessen Ausgabeformat in der Spezifikation eines anderen Anbieters definiert ist, deutet das darauf hin, dass das Format nicht mehr nur ein Feature eines einzelnen Produkts ist.

Was Sie zuerst schreiben sollten

Planen Sie keine Bibliothek. Warten Sie, bis Sie sich zum dritten Mal dabei ertappen, dieselben Anweisungen in einen Chat einzufügen. Verschieben Sie diesen Text dann in eine SKILL.md und löschen Sie die eingefügte Kopie. Bereits erlebte Wiederholung ist der einzige zuverlässige Auslöser für eine Fähigkeit, die sich dauerhaft lohnt. Ein Suchverfahren ist ein guter Anfang. Eine Suchfähigkeit mit eigener SearXNG-Instanz zeigt die Struktur.

Zwei Gewohnheiten halten die Bibliothek funktionsfähig. Lesen Sie jede Fähigkeit, die Sie nicht selbst geschrieben haben, vor der Installation vollständig durch, einschließlich der Skripte. Eine Fähigkeit enthält Anweisungen, die Ihr Agent befolgt, und Code, den er ausführen kann. Behandeln Sie sie daher wie die Installation von Software aus unbekannter 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 abgelegt werden. Der Lernfahrplan für Agents in diesem Jahr ordnet Fähigkeiten gemeinsam 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. Ein Agent-Skill ist ein Verzeichnis mit einer SKILL.md-Datei. Er benötigt weder einen Prozess noch ein Protokoll und belegt etwa 100 Tokens, bis der Agent entscheidet, ihn zu lesen. Verwenden Sie einen MCP-Server, um einem Agenten Zugriff auf ein System zu geben. Verwenden Sie einen Skill, um dem Agenten die korrekte Vorgehensweise 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. Unterschiede bestehen darin, wo die einzelnen Clients suchen und welche zusätzlichen Frontmatter-Felder sie verstehen. Claude Code liest ~/.claude/skills/ und .claude/skills/, während GitHub Copilot und VS Code .github/skills/ im Repository lesen. Die Datei SKILL.md selbst kann unverändert zwischen den Clients übertragen werden.

Wie viele Skills kann ich installieren, bevor sich die Verarbeitung verlangsamt?

Entscheidend ist das Startbudget, nicht die Anzahl. Jeder installierte Skill trägt seinen Namen und seine Beschreibung bei. Nach den veröffentlichten Vorgaben der Spezifikation sind das ungefähr 100 Tokens. Dreißig Skills belegen daher etwa 3,000 Tokens, bevor einer davon verwendet wird. Zuerst verschlechtert sich nicht die Geschwindigkeit, sondern die Zuordnung: Viele Skills mit ähnlichen Beschreibungen erschweren es dem Modell, den richtigen Skill auszuwählen. Schreiben 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, der einheitliche Schreibstil und Namensregeln gelten für alle Aufgaben. Sie gehören daher in die Datei, die immer geladen wird. Genau dafür wird diese Datei bei jedem Durchlauf geladen. Eine Vorgehensweise, die Sie nur gelegentlich ausführen, beispielsweise eine Release-Checkliste oder eine Restore-Übung, sollte ein Skill sein. Dadurch entstehen bei Aufgaben, die ihn nicht benötigen, keine Kosten. Ein Abschnitt von AGENTS.md, der zu nummerierten Schritten angewachsen ist, ist normalerweise ein Skill, der verschoben werden sollte.