Was sind Agent Skills und wie schreibt man SKILL.md?

Was ist ein Skill, und was unterscheidet ihn von der Regeldatei?

Nach der Definition des offenen Standards ist ein Skill ein Ordner, in dem eine Datei SKILL.md liegt. Oben in der Datei stehen mindestens ein Name (name) und eine Beschreibung (description), darunter Anweisungen, wie der Agent eine Aufgabe erledigt. Im Ordner können außerdem Skripte, Nachschlagedokumente und Vorlagen liegen.

Entwickelt hat das Format Anthropic. Claude Code bekam die Unterstützung für Skills am 16. Oktober 2025 mit Version 2.0.20; als offenen Standard veröffentlichte Anthropic das Format am 18. Dezember 2025. Stand 18. Oktober 2026 schreiben die Skill-Seiten von Claude Code, Codex, Cursor, Gemini CLI und Copilot, dass sie auf diesem Standard aufbauen. Die eigene Liste des Standards nennt 46 Produkte; laut der Website des Standards zeigt sie nur einen Teil der Produkte, die ihn unterstützen. Am 18. Juni 2026 hat Google Gemini CLI für kostenlose Nutzer sowie für Abonnenten von Google AI Pro und Ultra durch Antigravity CLI ersetzt; mit Firmenlizenz oder kostenpflichtigem API-Schlüssel bleibt Gemini CLI verfügbar. Auch Antigravity liest Skills und sucht Projekt-Skills in .agents/skills.

Der Unterschied zur Regeldatei (AGENTS.md, CLAUDE.md, GEMINI.md) liegt im Zeitpunkt, zu dem gelesen wird. Die Regeldatei wird in jeder Sitzung vollständig gelesen. Die Anweisungen eines Skills werden dagegen erst geladen, wenn eine Aufgabe dazu passt. Die Tools sagen das mit eigenen Worten:

• Claude Code: Anders als CLAUDE.md wird der Hauptteil eines Skills nur geladen, wenn der Skill genutzt wird. Lange Nachschlagetexte belegen deshalb kaum Platz, bis sie gebraucht werden.
• Gemini CLI: Kontextdateien wie GEMINI.md geben dem Arbeitsbereich einen ständigen Hintergrund; ein Skill ist Fachwissen, das bei Bedarf geöffnet wird.
• Codex: AGENTS.md bestimmt das Verhalten des Agenten, Skills bündeln wiederkehrende Abläufe.
• Copilot: Einfache Anweisungen, die für fast jede Aufgabe gelten, gehören in die Custom Instructions; ausführliche Anweisungen, die nur bei Bedarf gelesen werden sollen, gehören in einen Skill.

Auch ältere Formate wandern zu Skills. In Claude Code wurden die Befehle unter .claude/commands/ mit Skills zusammengelegt. Codex hat Custom Prompts als veraltet eingestuft und empfiehlt stattdessen Skills. Cursor bringt einen Skill /migrate-to-skills mit, der Regeln und Slash-Befehle in Skills umwandelt.

Regeldateien haben wir in unserem Beitrag zu AGENTS.md und CLAUDE.md behandelt, Befehle, die jedes Mal laufen, in unserem Beitrag zu Hooks, und Helfer, die in einem eigenen Kontext arbeiten, in unserem Beitrag zu Subagenten. Dieser Beitrag beschreibt die Ebene dazwischen: Anweisungen, die der Agent nur bei Bedarf öffnet.

Wann liest der Agent einen Skill?

Der Standard nennt das Progressive Disclosure, also schrittweises Laden. Der Agent liest einen Skill nicht auf einmal, sondern Stück für Stück, so wie die Aufgabe es verlangt:

Den ersten Schritt bezahlt jede Sitzung, auch wenn der Skill nie genutzt wird. Deshalb spielt es eine Rolle, wie viele Skills Sie installieren. Wie viel Platz diese Liste bekommt, schreiben zwei Tools:

• Claude Code gibt der Liste 1 % des Kontextfensters des Modells. Passt die Liste nicht hinein, entfernt es die Beschreibungen der Skills, die Sie am seltensten nutzen. Außerdem wird jede Beschreibung in der Liste nach 1.536 Zeichen abgeschnitten.
• Codex gibt der Liste höchstens 2 % des Kontextfensters, oder 8.000 Zeichen, wenn es das Fenster nicht kennt. Mit skills.max_context_tokens lässt sich dieser Anteil auf höchstens 10.000 Tokens anheben. Sind viele Skills installiert, kürzt Codex zuerst die Beschreibungen.
• Cursor, Gemini CLI und Copilot: Steht nicht in der Dokumentation.

Auch nach dem Öffnen belegt ein Skill Platz. In Claude Code gelangt der Inhalt eines aufgerufenen Skills als eine einzige Nachricht in die Unterhaltung und bleibt dort in den folgenden Runden. Wird die Unterhaltung komprimiert, kommen von jedem Skill nur die ersten 5.000 Tokens zurück. Schreiben Sie die wichtigste Anweisung deshalb an den Anfang der Datei.

Wo liegen Skills in den fünf Tools?

Der Standard legt fest, was in einen Skill-Ordner gehört, aber nicht, wo der Ordner liegt. Sein Leitfaden für Tool-Entwickler sagt das ausdrücklich und beschreibt .agents/skills als gemeinsamen Ordner, der sich zwischen den Tools durchsetzt. So stand es am 18. Oktober 2026 in der Dokumentation der fünf Tools:

Quelle: die Skill-Dokumentation des jeweiligen Tools, 18. Oktober 2026. In diesen Ordnern liegt jeder Skill in einem eigenen Unterordner: .agents/skills/<name>/SKILL.md. Cursor liest die Ordner von Claude Code und Codex aus Kompatibilitätsgründen. Die persönlichen Ordner von Copilot stammen aus der CLI-Dokumentation; die Dokumentation von VS Code nennt zusätzlich ~/.claude/skills. „Steht nicht in der Dokumentation“ heißt: Auf den Seiten, die wir an diesem Tag gelesen haben, fanden wir keinen Satz dazu.

Keinen Ordner nennt die Dokumentation aller fünf Tools. .agents/skills lesen vier Tools; die Dokumentation von Claude Code nennt nur .claude/skills und sagt nichts zu .agents/skills. .claude/skills lesen neben Claude Code auch Cursor und Copilot; die Dokumentation von Codex und Gemini CLI nennt diesen Ordner nicht. Dass ein Ordner nicht in der Dokumentation steht, heißt nicht, dass das Tool ihn nicht liest. Wer sich aber auf die Dokumentation verlässt, findet keinen einzelnen Ordner, mit dem sich ein Skill sicher in allen fünf Tools öffnet.

Auch bei zwei Skills mit gleichem Namen verhalten sich die Tools verschieden. Der Leitfaden des Standards beschreibt es als gemeinsame Konvention aller Tools, dass der Projekt-Skill dem persönlichen vorgeht; die Dokumentation von Gemini CLI und Copilot CLI hält sich daran. In der Dokumentation von Claude Code ist die Reihenfolge umgekehrt: Der persönliche Skill geht dem im Projekt vor. Codex führt die beiden nicht zusammen und zeigt beide in der Liste.

Auch Unterordner werden unterschiedlich gelesen. Claude Code und Codex lesen jeden skills-Ordner vom Ordner, in dem Sie die Sitzung gestartet haben, bis hinauf zum Wurzelverzeichnis des Repositorys. Cursor findet jeden Ordner .cursor/skills oder .agents/skills im Repository und schlägt die Skills darin nur vor, während Sie mit Dateien in diesem Ordner arbeiten. Gemini CLI schaut im skills-Ordner nur eine Ebene tief: .gemini/skills/<name>/SKILL.md wird gefunden, alles darunter nicht.

Wie nutzt man denselben Skill in allen fünf Tools?

Liegen Ihre Skills in .agents/skills, lesen Codex, Cursor, Gemini CLI und Copilot sie; für Claude Code braucht es einen Schritt mehr. Der kürzeste Weg, den die Dokumentation stützt: Schreiben Sie den Skill unter .agents/skills/<name>/ und lassen Sie .claude/skills/<name> per Symlink darauf zeigen.

mkdir -p .claude/skills
# der Skill liegt in .agents/skills/pr-zusammenfassung/SKILL.md
ln -s ../../.agents/skills/pr-zusammenfassung .claude/skills/pr-zusammenfassung
git add .claude/skills/pr-zusammenfassung

Die Dokumentation von Claude Code schreibt, dass ein Skill-Ordner (.claude/skills/<name>) ein Symlink auf einen Ordner an anderer Stelle sein darf. Zeigen mehrere Orte auf dasselbe Ziel, lädt Claude Code den Skill trotzdem nur einmal. Den ganzen Ordner .claude/skills zu einem einzigen Symlink zu machen, erwähnt die Dokumentation nicht; sie beschreibt einen Link pro Skill. Wenn Sie in die andere Richtung verlinken: Auch die Dokumentation von Codex schreibt, dass Codex dem Ziel verlinkter Skill-Ordner folgt.

Arbeitet jemand im Team unter Windows, achten Sie auf eines. Laut der Git-Dokumentation wird ein Symlink bei ausgeschaltetem core.symlinks als kleine Textdatei ausgecheckt, in der der Pfad des Links steht. Und git clone schaltet diese Einstellung selbst aus, wenn das Dateisystem keine Symlinks unterstützt. Prüfen Sie deshalb eigens, ob der Link auf diesem Rechner funktioniert.

Wir haben uns auch angesehen, was beliebte Repositorys tun. Für den Beitrag zu AGENTS.md hatten wir am 13. Oktober 2026 die 100 Repositorys mit den meisten Sternen untersucht; diesmal haben wir in denselben Dateibäumen nach SKILL.md gesucht. Von den 98 Repositorys, deren Dateibaum wir vollständig lesen konnten, haben 41 mindestens eine SKILL.md. Davon legen 21 ihre Skills in einem Tool-Ordner im Wurzelverzeichnis ab:

Am häufigsten ist .agents/skills, der Ordner, den vier Tools lesen. 7 Repositorys verbinden die beiden Ordner per Symlink. Bei 5 davon zeigt .claude/skills auf .agents/skills, bei 1 umgekehrt .agents/skills auf .claude/skills, und bei 1 zeigt .claude/skills auf den Copilot-Ordner .github/skills. vercel/next.js und flutter/flutter verlinken den ganzen Ordner .claude/skills. langgenius/dify verlinkt dagegen jeden Skill einzeln, also so, wie es die Dokumentation von Claude Code beschreibt.

Was gehört an den Anfang einer SKILL.md?

Eine SKILL.md besteht aus zwei Teilen: ganz oben YAML zwischen zwei Zeilen --- (das Frontmatter), darunter Anweisungen in Markdown. Der Standard definiert sechs Felder für das Frontmatter:

Quelle: Spezifikation von Agent Skills, 18. Oktober 2026.

Die Tools wenden diese Regeln unterschiedlich streng an:

• In Claude Code sind alle Felder optional, nur description wird empfohlen. Fehlt name, wird der Name des Ordners verwendet. Felder, die es nicht kennt, ignoriert Claude Code ohne Fehlermeldung.
• Codex, Cursor, Gemini CLI und Copilot verlangen name und description.
• Gemini CLI überspringt die Datei stillschweigend, wenn eines der beiden Felder fehlt oder vor der ersten Zeile --- irgendetwas steht (eine Überschrift, ein Kommentar, sogar eine Leerzeile). Den Namen des Skills nimmt es außerdem aus dem Feld name, nicht aus dem Ordner; der Standard und Cursor verlangen dagegen, dass der Name dem Ordnernamen entspricht.
• Copilot CLI erlaubt im Namen auch Großbuchstaben, Leerzeichen, Unterstriche, Punkte und Doppelpunkte. Der Standard lässt nur Kleinbuchstaben, Ziffern und Bindestriche zu.

Die Regeln zu XML-Tags stammen nicht vom Standard, sondern von Anthropic. Nach den Regeln von Anthropic für claude.ai und die API dürfen name und description keine XML-Tags enthalten, und name darf die Wörter “anthropic” und “claude” nicht enthalten. Felder, die es nur in Claude Code gibt (etwa when_to_use, context und hooks), funktionieren in Claude Code. Laden Sie denselben Skill aber nach claude.ai oder in die Skills API hoch, bricht jedes Feld außerhalb des Standards den Upload ab: Unexpected key(s) in SKILL.md frontmatter.

Wollen Sie einen Skill in mehreren Tools nutzen, beginnen Sie nur mit den Feldern des Standards. Das Beispiel unten nutzt nur die beiden Pflichtfelder und hält sich an die Feldregeln in der Dokumentation aller fünf Tools:

Wenn Sie entscheiden, was in den Hauptteil kommt, stellen Sie jeder Zeile die Frage aus dem Leitfaden des Standards: Würde der Agent diese Aufgabe ohne diese Anweisung falsch machen? Lautet die Antwort Nein, löschen Sie die Zeile. Verschieben Sie lange Nachschlagetexte nach references/ und verlinken Sie sie direkt aus der SKILL.md. Der Standard und der Leitfaden von Anthropic empfehlen beide, Nachschlagedateien nur eine Ebene von der SKILL.md entfernt abzulegen.

Was gehört in die Beschreibung?

Bevor der Agent einen Skill wählt, sieht er nur dessen Beschreibung. Der Leitfaden des Standards sagt es deutlich: “the description carries the entire burden of triggering.” Die Dokumentation der Tools sagt dasselbe: Claude Code, Codex, Cursor und Copilot wählen einen Skill anhand seiner Beschreibung. Auch laut dem Leitfaden von Gemini CLI ist die Beschreibung die einzige Information, die das Modell hat, bevor es den Skill öffnet.

• Schreiben Sie, was der Skill tut und wann er gebraucht wird. Der Standard, Claude Code, Cursor und Copilot verlangen beides zusammen. Eine Beschreibung wie “Helps with PDFs.” sagt dem Agenten nichts; sie ist das schlechte Beispiel aus dem Standard selbst.
• Nutzen Sie die Wörter Ihrer Nutzer. Die Liste zur Fehlersuche von Claude Code beginnt genau hier: Enthält die Beschreibung Schlüsselwörter, die Nutzer ganz natürlich sagen würden?
• Setzen Sie das Wichtigste an den Anfang. Passt die Liste nicht, werden Beschreibungen gekürzt. Claude Code schneidet jede Beschreibung in der Liste nach 1.536 Zeichen ab. Codex kürzt bei vielen installierten Skills zuerst die Beschreibungen; seine Dokumentation empfiehlt deshalb, Anwendungsfall und Auslösewörter an den Anfang zu stellen.
• Grenzen Sie ihn von ähnlichen Skills ab. Der Leitfaden von Gemini CLI verlangt Beschreibungen, die sich voneinander unterscheiden und auch von dem, was das Modell ohnehin kann.

Bei der Perspektive gehen die Leitfäden auseinander. Der Leitfaden von Anthropic verlangt die dritte Person und schreibt, dass Beschreibungen, die mit “I can help you…” oder “You can use this…” beginnen, das Auffinden stören können. Der Leitfaden von agentskills.io empfiehlt dagegen, die Beschreibung wie eine Anweisung an den Agenten zu schreiben, nach dem Muster “Use this skill when…”. Die Beispiele beider Leitfäden gehen denselben Weg: zuerst, was der Skill tut, dann mit “Use when…”, wann er genutzt wird. Auch das Beispiel oben ist so geschrieben.

Auch eine gute Beschreibung garantiert nicht, dass der Skill jedes Mal geöffnet wird. Laut dem Leitfaden des Standards greifen Agenten vor allem bei Aufgaben auf Skills zurück, die sie allein nicht schaffen. Eine Bitte in einem Schritt wie „Lies dieses PDF“ öffnet einen PDF-Skill unter Umständen nicht, selbst wenn die Beschreibung genau passt. Für Copilot schreibt auch die Dokumentation von VS Code, dass das Auffinden nicht garantiert, dass der Skill bei jedem passenden Prompt aufgerufen wird.

Rufen Sie den Skill selbst auf, oder wählt ihn der Agent?

Beides geht. In allen fünf Tools kann der Agent einen Skill, den er für die Aufgabe passend findet, von selbst öffnen. Wie Sie einen Skill von Hand aufrufen und wie Sie verhindern, dass der Agent ihn selbst wählt, hängt vom Tool ab:

Quelle: die Skill-Dokumentation des jeweiligen Tools, 18. Oktober 2026. In Claude Code und Copilot bewirkt user-invocable: false das Gegenteil: Nur der Agent kann den Skill öffnen.

Bei Aufgaben mit Nebenwirkungen schalten Sie die eigene Wahl des Agenten ab. Die Dokumentation von Claude Code sagt es so: “You don't want Claude deciding to deploy because your code looks ready.” Skills, die deployen, committen oder Nachrichten verschicken, gehören dazu. Mit dieser Einstellung setzt Claude Code die Beschreibung des Skills gar nicht erst in den Kontext, sie belegt also auch keinen Platz in der Liste. Ein Beispiel für einen Skill, den Sie von Hand aufrufen und der eine Review-Anfrage zum Befehl /pruefen macht, finden Sie in unserem Beitrag zum Code-Review-Prompt.

In Gemini CLI ist es anders: activate_skill, das Werkzeug, das einen Skill öffnet, kann nur der Agent aufrufen, nicht Sie. Dafür fragt der Agent jedes Mal, wenn er einen Skill öffnet, um Ihre Zustimmung.

Woran erkennt man, ob ein Skill funktioniert?

Die Dokumentation von Claude Code beginnt mit einer Warnung: “Seeing a skill trigger tells you Claude found it, not that it did what you intended.” Ob ein Skill geöffnet wird und ob er die Aufgabe richtig erledigt, sind zwei getrennte Fragen, und jede wird für sich gemessen.

Gemessen werden beide durch Vergleich. Sammeln Sie einige realistische Prompts; führen Sie jeden in einer neuen Sitzung einmal mit eingeschaltetem und einmal mit ausgeschaltetem Skill aus und legen Sie die Ergebnisse nebeneinander. Die neue Sitzung ist wichtig, weil der Kontext, der beim Schreiben des Skills entstanden ist, Lücken in den Anweisungen verdeckt.

Um zu messen, wie oft ein Skill geöffnet wird, gibt der Leitfaden von agentskills.io ein konkretes Rezept:

• Schreiben Sie etwa 20 Prompts: Die Hälfte soll den Skill öffnen, die andere Hälfte nicht.
• Nehmen Sie die Prompts, die ihn nicht öffnen sollen, aus ähnlichen Aufgaben. Prompts mit denselben Wörtern, die aber etwas anderes wollen, zeigen am besten, wie trennscharf die Beschreibung ist.
• Das Modell entscheidet nicht jedes Mal gleich. Führen Sie jeden Prompt mehrmals aus (3 Mal ist ein guter Anfang) und berechnen Sie, wie oft der Skill geöffnet wurde.
• Als Schwelle ist 0,5 vernünftig: Bei Prompts, die den Skill öffnen sollen, sollte die Quote darüber liegen, bei den anderen darunter.

Ein einzelner Versuch zählt deshalb nicht als Ergebnis. Dass derselbe Prompt den Skill in einem Lauf öffnet und im nächsten nicht, ist normal; wenn Sie eine Beschreibung ändern, führen Sie dieselben Prompts genauso oft erneut aus.

Was prüft man, bevor man einen fremden Skill installiert?

Ein Skill ist nicht nur Text: Er kann Skripte ausführen, bestimmte Werkzeuge ohne Rückfrage freigeben und den Agenten mit seinen Anweisungen lenken. Die Dokumentation von Anthropic schreibt, dass ein bösartiger Skill den Agenten zu Werkzeugaufrufen oder Codeausführung bringen kann, die nicht zu seinem angegebenen Zweck passen, und empfiehlt, Skills nur aus Quellen zu nutzen, denen Sie vertrauen.

Beim Vertrauen verhalten sich die Tools unterschiedlich:

• Claude Code wendet das Feld allowed-tools eines Projekt-Skills sogar in einem -p-Lauf in einem Ordner an, dem Sie nie vertraut haben. Die Dokumentation bittet deshalb, dieses Feld in Skills aus dem Repository zu lesen, bevor Sie Claude Code dort starten. Das Feld schränkt keine Werkzeuge ein; es erlaubt, die aufgeführten Werkzeuge in der Runde, in der der Skill aufgerufen wird, ohne Rückfrage zu nutzen.
• Copilot schreibt, dass mit gh skill installierte Skills nicht von GitHub geprüft werden und Prompt Injection, versteckte Anweisungen oder schädliche Skripte enthalten können. Vor der Installation empfiehlt es einen Blick mit gh skill preview.
• Gemini CLI lässt Sie bei der Installation von einer entfernten Adresse die Quelle bestätigen und fragt jedes Mal um Erlaubnis, wenn es einen Skill öffnet. Projekt-Skills unter .gemini/skills lädt es außerdem nur, wenn der Arbeitsordner als vertrauenswürdig markiert ist.
• Codex und Cursor haben auf ihren Skill-Seiten keine Regel zum Vertrauen: Steht nicht in der Dokumentation.

Auch der Leitfaden des Standards für Tool-Entwickler empfiehlt, Projekt-Skills nur in Ordnern zu laden, die als vertrauenswürdig markiert sind. Ein frisch geklontes Repository kann unbemerkt Anweisungen in den Kontext des Agenten bringen.

Wann nimmt man einen Skill, wann AGENTS.md?

Das eine ersetzt das andere nicht, und beliebte Repositorys nutzen beides. Von den 41 untersuchten Repositorys mit einer SKILL.md haben 35 im Wurzelverzeichnis auch eine AGENTS.md oder CLAUDE.md.

Entscheidend ist, wann eine Information gebraucht wird. Was für jede Aufgabe gilt (der Aufbau des Projekts, Build-Befehle, Regeln wie „Mach das nie“), gehört in die Regeldatei; ein Ablauf, den Sie ab und zu brauchen, oder ein langer Nachschlagetext gehört in einen Skill. Der Maßstab aus der Dokumentation von Claude Code hilft: Ist ein Abschnitt in CLAUDE.md keine Information mehr, sondern ein Ablauf, machen Sie einen Skill daraus.

Vercel ist dieser Frage in einem Beitrag vom 27. Januar 2026 mit eigenen Tests nachgegangen. In Tests zu den APIs von Next.js 16 wurde der Skill in 56 % der Fälle gar nicht aufgerufen. Ein 8 KB großer Dokumentationsindex, direkt in AGENTS.md eingebettet, erreichte eine Erfolgsquote von 100 %; das beste Ergebnis des Skills lag bei 79 %. Das ist die Messung eines einzigen Teams zu einem einzigen Thema, und der Beitrag sagt auch nicht, mit wie vielen Aufgaben gemessen wurde. Vercels eigenes Fazit lautet auch nicht „entweder oder“: “The two approaches complement each other.” Laut dem Beitrag funktionieren bestimmte Abläufe, die der Nutzer ausdrücklich startet, als Skill besser.

Eine Regel, die in jedem Pull Request gelten muss, ist ebenfalls Sache der Regeldatei. Wenn diffox einen Pull Request prüft, liest es die AGENTS.md im Wurzelverzeichnis des Repositorys, sonst die CLAUDE.md, und nutzt die Regeln darin als Review-Regeln. Soll eine Regel in jedem Review gelten, schreiben Sie sie in die Regeldatei.