Agent Skills: der SKILL.md-Leitfaden für Claude Code und Codex

Ein Skill ist ein Ordner mit einer Datei SKILL.md. Ihn zu schreiben ist der leichte Teil. Der Rest verlangt zu wissen, wo man ihn ablegt, damit der Agent ihn findet, zu prüfen, ob er wirklich auslöst, und zu messen, was er die restliche Zeit kostet. Dieser Leitfaden macht alle drei, an einem Skill, der eigens dafür gebaut und ausgeführt wurde.

Was ist ein Skill eigentlich genau?

Das Format Agent Skills wurde von Anthropic geschaffen und anschließend als offener Standard veröffentlicht, die Spezifikation lebt heute auf agentskills.io. Sie besteht aus wenig: einem Ordner, einer verpflichtenden SKILL.md, und was du sonst noch danebenlegen willst.

regex-verifiee/
├── SKILL.md          # verpflichtend: YAML-Frontmatter + Markdown-Anweisungen
├── scripts/          # optional: Code, den der Agent ausführt
├── references/       # optional: Dokumentation, bei Bedarf geladen
└── examples/         # optional: Vorlagen, Testdaten

Das Frontmatter ist kurz und streng geregelt. name: höchstens 64 Zeichen, nur Kleinbuchstaben, Ziffern und Bindestriche, kein Bindestrich am Anfang oder Ende, kein doppelter Bindestrich, und er muss exakt dem Namen des übergeordneten Ordners entsprechen. description: verpflichtend, höchstens 1.024 Zeichen, sie sagt, was der Skill tut und wann man ihn einsetzt. Drei optionale Felder vervollständigen das Ganze: license, compatibility (500 Zeichen) und metadata. Ein sechstes, allowed-tools, ist in der Spezifikation als experimentell markiert.

Der Mechanismus, der die Sache interessant macht, heißt progressive Offenlegung, in drei Stufen. Beim Start lädt der Agent nur name und description jedes Skills, die Spezifikation zielt auf etwa hundert Tokens. Passt eine Aufgabe dazu, liest er den Hauptteil der SKILL.md (unter 5.000 empfohlenen Tokens, maximal 500 Zeilen). Erst danach, falls nötig, öffnet er die Dateien in scripts/, references/ oder assets/. Anthropics Engineering-Beitrag vom 16. Oktober 2025 formuliert es andersherum: Kümmere dich um name und description, denn genau daran, und nur daran, entscheidet der Agent, ob er den Skill auslöst.

Ein Skill, der nie auslöst, kostet also trotzdem seine Beschreibung, bei jeder Sitzung, in jedem Kontextfenster. Genau das misst der Befehl /skill-doctor von Claude Code, und das ist der erste Ausgabenposten, der im Erfahrungsbericht von Spotify zur Token-Rechnung untersucht wird.

Wo sucht jeder Agent nach Skills?

Das ist der Teil, den niemand korrekt hinschreibt, weil er von Tool zu Tool wechselt. Hier die Pfade, wie sie in der Dokumentation jedes Anbieters stehen, aufgerufen am 7. September 2026.

Daraus folgen zwei Dinge. .agents/skills wird gerade zum gemeinsamen neutralen Pfad, Codex, Copilot und OpenCode lesen ihn alle drei. Und Copilot wie OpenCode lesen auch .claude/skills, der Ordner von Claude Code dient de facto als Austauschformat. Derselbe Skill-Ordner kann also mehreren Agenten dienen, ohne dupliziert zu werden. Auf der Oberflächenseite kündigt GitHub Skills an für den Cloud-Agenten, die Code-Review, Copilot CLI, die GitHub-Copilot-App und den Agentenmodus von VS Code und den JetBrains-IDEs.

Am 7. September 2026 verzeichnet die Übersicht von agentskills.io 46 kompatible Produkte, von Cursor bis Goose, über Junie, Kiro, Roo Code, Laravel Boost, OpenCode und OpenClaw.

Einen nützlichen Skill bauen: regex-verifiee

Ein guter Skill kodiert eine Prozedur, die du wiederholst und die der Agent überspringt, wenn man sie ihm nicht aufzwingt. Der hier gewählte Fall: reguläre Ausdrücke. Ein Agent liefert dir eine Regex in drei Sekunden, ohne sie je an einem Gegenbeispiel zu testen. Der Skill regex-verifiee verbietet genau diese Art von Antwort.

Die SKILL.md, vollständig für das Frontmatter und den Anfang des Hauptteils:

---
name: regex-verifiee
description: Écrire une expression régulière et la prouver avant de la livrer. À utiliser dès qu'une demande porte sur une regex, une expression régulière, une validation de format (code postal, SIRET, IBAN, e-mail, téléphone, slug, plaque), un preg_match, un preg_replace ou un RegExp. Impose un fichier de cas valides et invalides, son exécution dans le moteur cible (Node et PHP), puis la livraison regex + tableau de cas + limites.
---

# Regex vérifiée

Une regex qui n'a jamais tourné sur ses contre-exemples n'est pas une regex, c'est une intuition.
Suivez ces cinq étapes dans l'ordre. Ne sautez pas l'étape 4.

## Procédure

1. **Cadrer.** Demandez, ou décidez explicitement : le moteur (JavaScript, PCRE/PHP, POSIX), la
   chaîne testée (déjà nettoyée ou brute), et si la valeur peut être vide.
2. **Proposer.** Écrivez la regex ancrée et, en une phrase par groupe, ce que chaque partie accepte.
3. **Écrire les cas.** Créez un fichier JSON : au moins six valides et six invalides. Les invalides
   doivent inclure les pièges de `references/cas-types.md` pour le type de donnée concerné.
4. **Exécuter.** Lancez le script sur les deux moteurs et collez la sortie brute dans la réponse.
5. **Livrer.** Réponse finale = la regex + le tableau de cas produit par le script + les limites.

Die Beschreibung ist absichtlich geschwätzig mit Auslösevokabular: „regex“, „regulärer Ausdruck“, „Postleitzahl“, „SIRET“, „preg_match“, „RegExp“. Das sind die Wörter, die der Leser tatsächlich eingibt. Schreib sie in der Sprache, in der man mit dir spricht, nicht in der der Dokumentation.

Der Ordner enthält außerdem eine Falldatei im JSON-Format, zwei Ausführer (einen in Node, einen in PHP), die dieselbe Datei lesen, und eine Referenz references/cas-types.md, die die Gegenbeispiele nach Datentyp auflistet. Die Falldatei sieht so aus:

{
  "name": "code postal français",
  "engine": "both",
  "pattern": "^(?:0[1-9]|[1-8]\\d|9[0-8])\\d{3}$",
  "flags": "",
  "valid": ["01000", "20000", "62500", "75001", "97400", "98000"],
  "invalid": ["", "00000", "99999", "7500", "750011", "75 001", "2A000", " 75001", "75001\n"]
}

Beide Ausführer geben dieselbe Tabelle aus und liefern einen von null verschiedenen Exit-Code, sobald ein Fall fehlschlägt. Dieser Exit-Code leistet die eigentliche Arbeit: Der Agent kann bei einem fehlerhaften Befehl keinen Schlussstrich ziehen.

Erste Überraschung, die sich zeigte, als ich das Testgeschirr selbst laufen ließ, noch bevor überhaupt ein Agent im Spiel war: Dieselbe Regex liefert in den beiden Engines nicht dasselbe Urteil.

$ node scripts/verifier.mjs examples/code-postal-fr.json
moteur : node v22.23.2
regex  : /^(?:0[1-9]|[1-8]\d|9[0-8])\d{3}$/
...
"75001\n"  false    false   ok

15 cas, 0 échec(s)

$ php scripts/verifier.php examples/code-postal-fr.json
moteur : PHP 8.4.19, PCRE 10.47 2025-10-21
regex  : /^(?:0[1-9]|[1-8]\d|9[0-8])\d{3}$/
...
"75001\n"  false    true    ECHEC

15 cas, 1 échec(s)

In PCRE akzeptiert $ einen abschließenden Zeilenumbruch, in JavaScript nicht. Ein Formularfeld, das mit einem angehängten \n ankommt, besteht also die PHP-Validierung und scheitert an der JavaScript-Validierung, mit derselben Expression in beiden Dateien. Zwei Korrekturen, beide hier verifiziert: der Modifikator D auf PHP-Seite (preg_match('/^\d{5}$/D', "75001\n") liefert 0), oder ein portabler Anker (?![\s\S]) anstelle von $, der alle fünfzehn Fälle in beiden Engines besteht.

Mit Codex testen, ohne ~/.codex anzufassen

Die Dokumentation von Codex beschreibt einen Stapel von Wurzelverzeichnissen: $CWD/.agents/skills, die übergeordneten Ordner, $REPO_ROOT/.agents/skills, dann $HOME/.agents/skills, /etc/codex/skills und die mit der CLI ausgelieferten Skills. Mit anderen Worten: Ein projektbezogener Skill existiert wirklich, du musst weder in ~/.codex/skills noch in ~/.codex/config.toml schreiben, um ihn auszuprobieren.

Bleibt zu prüfen, was die Binärdatei tatsächlich tut. Codex stellt dafür einen Debug-Befehl bereit, der den Prompt genau so zeigt, wie das Modell ihn erhält, ohne das Modell aufzurufen:

$ mkdir -p demo-projet/.codex/skills
$ cp -R regex-verifiee demo-projet/.codex/skills/
$ cd demo-projet && codex debug prompt-input "test"

### Skill roots
- `r0` = `/…/demo-projet/.codex/skills`
- `r1` = `/Users/gekkode/.codex/skills`
- `r2` = `/Users/gekkode/.agents/skills`
- `r3` = `/Users/gekkode/.codex/skills/.system`
- `r4` … `r10` = caches de plugins
### Available skills
- regex-verifiee: Écrire une expression régulière et la prouver avant de la livrer. À utiliser dès qu'une deman (file: r0/regex-verifiee/SKILL.md)

Der Skill wird gesehen, aus <projet>/.codex/skills, einem Pfad, den die Dokumentation nicht erwähnt, den die Binärdatei aber tatsächlich scannt, und zwar an erster Stelle. Als ein zweiter Testskill in <projet>/.agents/skills abgelegt wurde, erschien eine Wurzel r11 mit diesem Pfad: Beide funktionieren, und der Ordner .codex/ kommt zuerst.

Nun zum echten Test. Derselbe Prompt, dasselbe Modell, dieselbe Maschine, im Abstand weniger Minuten: einmal im Projekt, das den Skill enthält, einmal in einem leeren Ordner.

codex exec -m gpt-6-astra -s workspace-write --skip-git-repo-check \
  "Dans un formulaire PHP, je dois valider le code postal saisi par le visiteur. Donne-moi l'expression reguliere a utiliser."

Ohne den Skill: 19 Sekunden, null ausgeführte Befehle, und diese Antwort, preg_match('/\A[0-9]{5}\z/', $codePostal), mit einem Satz, der sagt, die Expression prüfe das Format und nicht, ob die Postleitzahl tatsächlich existiert. Durch das Testgeschirr geschickt, scheitert diese Regex bei zwei von fünfzehn Fällen: Sie akzeptiert 00000 und 99999.

Mit dem Skill: 106 Sekunden, zehn ausgeführte Befehle. Codex hat die SKILL.md gelesen, dann die beiden Skripte, dann references/cas-types.md, die vollständige progressive Offenlegung, Stufe für Stufe. Anschließend schrieb er seine eigene Falldatei (achtzehn Fälle, darunter "75001\n00000" und "2a000", aus der Referenz übernommen), startete beide Ausführer und lieferte dies:

$codePostal = $_POST['code_postal'] ?? '';

$valide = is_string($codePostal)
    && preg_match('/\A(?:0[1-9]|[1-8][0-9]|9[0-8])[0-9]{3}\z/', $codePostal) === 1;

Darunter die beiden Tabellen mit je achtzehn Fällen und ein Abschnitt „Grenzen“. Beachte, dass er nicht in beiden Engines dieselbe Expression verwendet hat. \A … \z für PCRE, ^ … (?![\s\S]) für JavaScript. Der Skill hat ihm das nie gesagt, er hat es abgeleitet, indem er die Fälle ausführte.

Ein Skill von rund sechzig Zeilen hat also eine Drei-Sekunden-Antwort, die bei zwei Fällen falsch lag, in eine zweiminütige Prozedur verwandelt, deren Ergebnis überprüfbar ist. Der Auslöser geschah ganz von selbst, allein über die Beschreibung: Der Prompt enthält weder das Wort „skill“ noch den Namen regex-verifiee. In Codex lässt sich das auch mit $regex-verifiee im Prompt erzwingen, in Claude Code mit /regex-verifiee.

Was kostet eine Beschreibung, und warum wird sie gekürzt?

Während der Ausführung gab Codex eine Warnung aus, mit der ich nicht gerechnet hatte:

Skill descriptions were shortened to fit the skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest.

Überprüft mit einem Testskill, dessen Beschreibung aus dreihundert bekannten Zeichen besteht: Auf dieser Maschine, mit 146 installierten Skills, wird jede Beschreibung auf 94 Zeichen gekürzt. Meine 422 Zeichen lange Beschreibung kommt beim Modell also um zwei Drittel gekürzt an, mitten im Wort „demande“ abgeschnitten. Alles, was danach kommt, „SIRET“, „IBAN“, „preg_match“, „RegExp“, bringt für das Auslösen nichts mehr.

Das Budget lässt sich einstellen. Codex akzeptiert einen Schlüssel skills.max_context_tokens, den man als Override übergeben kann, ohne die Konfigurationsdatei zu bearbeiten:

codex debug prompt-input -c skills.max_context_tokens=16000 "test"

Daraus ergeben sich zwei Regeln. Setze die Auslösewörter in die ersten neunzig Zeichen der Beschreibung, der Rest ist Bonus. Und rechne damit, dass du mit jedem weiteren installierten Skill die Beschreibung aller anderen abrasierst. Der Katalog belegte hier 22.230 Zeichen Kontext, bei jeder Sitzung, für 146 Skills, von denen ich nur eine Handvoll benutze. Deinstallieren schlägt Budget-Erhöhen.

Claude Code wendet dasselbe Prinzip an, mit veröffentlichten Zahlen. Sein Listing-Budget beträgt 1 % des Kontextfensters des Modells, einstellbar über skillListingBudgetFraction oder die Umgebungsvariable SLASH_COMMAND_TOOL_CHAR_BUDGET. Jeder Eintrag ist ohnehin gedeckelt: description und when_to_use zusammen werden bei 1.536 Zeichen gekappt, eine Obergrenze, die sich über skillListingMaxDescChars einstellen lässt. Und wenn die Liste überläuft, ist die Dokumentation eindeutig über die Reihenfolge des Opferns: Claude Code entfernt zuerst die Beschreibungen der Skills, die du am seltensten aufrufst. Der Name dagegen bleibt immer in der Liste.

Beide Tools bieten denselben Ausweg: deaktivieren statt das Budget aufzublähen. Bei Claude Code akzeptiert die Einstellung skillOverrides vier Zustände pro Skill, on, name-only (der Name ohne Beschreibung), user-invocable-only und off, und der Befehl /skills schreibt sie für dich in die .claude/settings.local.json. Bei Codex ein Block in ~/.codex/config.toml:

[[skills.config]]
path = "/chemin/vers/le/skill/SKILL.md"
enabled = false

Denselben Skill in Claude Code laden und verteilen

Der Ordner ändert sich nicht. Zwei Orte, je nachdem, ob der Skill dich überallhin begleitet oder zum Repository gehört:

cp -R regex-verifiee ~/.claude/skills/          # für alle deine Projekte
cp -R regex-verifiee mon-projet/.claude/skills/ # mit dem Repository versioniert

Die Dokumentation von Claude Code fügt Frontmatter-Felder hinzu, die in der Spezifikation fehlen. disable-model-invocation: true verhindert das automatische Auslösen und reserviert den Skill für einen manuellen Aufruf per /nom, die richtige Einstellung für alles, was pusht, deployt oder löscht. allowed-tools gewährt Tool-Berechtigungen nur für die eine Gesprächsrunde, die den Skill aufruft, und die Berechtigung erlischt bei der nächsten Nachricht. user-invocable: false reserviert den Skill für das Modell.

Um den Skill an ein Team zu verteilen, ist die Verpackung ein Plugin: ein Manifest .claude-plugin/plugin.json im Wurzelverzeichnis, der Skill im Ordner skills/, und eine Datei .claude-plugin/marketplace.json, die den Marktplatz deklariert. Die Installation erfolgt dann über /plugin marketplace add compte/depot und anschließend /plugin install mon-plugin@ma-marketplace, und /reload-plugins lädt neu, ohne die Sitzung zu verlassen.

Bleibt die unangenehme Frage. Löst dein Skill überhaupt aus, und bringt er etwas? Claude Code beantwortet beide Hälften. /skill-doctor, das Version 2.1.252 oder neuer voraussetzt, listet die geladenen Skills, ihre Anzahl an Aufrufen und ihre letzte Nutzung auf und meldet die, die nie gebraucht wurden, der Bericht öffnet sich im Tab Stats des Plugin-Managers und wird im Modus -p als reiner Text ausgegeben. Und claude plugin eval, im Early Access, automatisiert genau den Vergleich, den ich weiter oben von Hand gemacht habe. Die Hilfe des Befehls, auf dieser Maschine, lässt keinen Zweifel:

$ claude plugin eval --help
Run eval cases (evals/**/case.yaml or evals/**/prompt.md + graders/*.md) against
a plugin and report scored results.

  --ablation <mode>   Run a no-plugin baseline arm and report the score delta
                      (none | with-without; default: with-without …)
  --runs <n>          Override per-case runs (default: case.runs ?? 3)
  --threshold <0..1>  Exit 1 if any case score is below this threshold
  --json              Emit aggregate-result.json to stdout (for CI)

Ein Eval-Fall ist ein Ordner evals/<cas>/ mit einer prompt.md, einem realistischen Prompt, der vor allem den Skill nicht beim Namen nennt, und Korrektoren in graders/. Die Option --ablation with-without spielt jeden Fall mit und ohne Plugin erneut ab und zeigt die Score-Differenz: Das ist der einzige ehrliche Weg zu beweisen, dass ein Skill etwas bringt.

Einen Skill teilen, und die anderer prüfen

Drei Vertriebswege bestehen nebeneinander. Ein einfaches Git-Repository, das man in den richtigen Ordner klont, der einfachste und am besten überprüfbare. Ein Plugin, für Claude Code wie für Codex: Bei Codex lebt jedes Plugin unter plugins/<nom>/ mit einem verpflichtenden Manifest .codex-plugin/plugin.json und optionalen Ordnern skills/, .app.json, .mcp.json. Und die öffentlichen Marktplätze: ClawHub, Skills.sh, SkillsMP.

Beachte nebenbei, dass der Katalog github.com/openai/skills, noch überall zitiert, als veraltet markiert ist und auf github.com/openai/plugins verweist. Der Systemskill $skill-installer dagegen installiert weiterhin nach $CODEX_HOME/skills/<nom>.

Der dritte Weg verlangt Misstrauen. Der von Snyk am 5. Februar 2026 veröffentlichte ToxicSkills-Audit hat 3.984 Skills von ClawHub und skills.sh durchleuchtet: 1.467 davon (36,82 %) weisen mindestens einen Sicherheitsmangel auf, und 534, 13,4 % der Gesamtzahl, mindestens einen kritischen Mangel. Sechsundsiebzig bösartige Payloads wurden durch menschliche Prüfung bestätigt: Diebstahl von Zugangsdaten, Installation einer Hintertür, Datenexfiltration, acht dieser Skills waren am Tag der Veröffentlichung noch online. Alle bestätigten Payloads enthalten bösartigen Code, und 91 % fügen zusätzlich Prompt-Injection hinzu.

Ein Skill ist Text, dem dein Agent folgen wird, plus Skripte, die er mit deinen Rechten ausführen wird. Bevor du einen installierst, lies die SKILL.md vollständig, lies jede Datei in scripts/, such nach Netzwerkaufrufen und base64-kodierten Zeichenketten, und lehne jeden Skill ab, der einen API-Schlüssel oder ein Token verlangt. Dieselben Reflexe wie für die Sandbox und die Berechtigungen eines Code-Agenten.

Skills oder MCP?

Skills und MCP beantworten nicht denselben Bedarf. Ein Skill liefert eine Prozedur und Know-how, in Markdown, ohne Prozess, ohne Netzwerk, ohne Authentifizierung. Ein MCP-Server liefert Werkzeuge und Daten: Er spricht mit einer Datenbank, einer API, einem entfernten Dateisystem, samt der dazugehörigen Zugangsdaten.

Der schnellste Test passt in einen Satz. Wenn sich dein Bedarf als „geh so vor“ formulieren lässt, ist es ein Skill. Wenn er sich als „hol das“ oder „schreib das irgendwohin“ formuliert, ist es ein MCP-Server. Der Kostenunterschied folgt derselben Linie: Ein untätiger Skill kostet seine Beschreibung, einige Dutzend Tokens, während ein angeschlossener MCP-Server die Definition all seiner Werkzeuge kostet, dauerhaft, bei jeder Sitzung.

Beide lassen sich sehr gut kombinieren: ein Skill, der sagt, in welcher Reihenfolge die Werkzeuge eines MCP-Servers aufzurufen sind, ist oft das Beste aus beiden Welten. Das ist im Übrigen auch die Richtung, die das Protokoll selbst einschlägt, die Revision 2026-07-28 der MCP-Spezifikation führt eine Arbeitsgruppe „Skills over MCP“, deren Aufgabe es ist, strukturierte Anweisungen über MCP zu entdecken und zu nutzen. Für den Server-Teil übernimmt der Leitfaden zum MCP-Server in PHP.

Die vier immer wiederkehrenden Fehler

Eine Beschreibung, die den Skill beschreibt, statt zu sagen, wann man ihn nutzt. „Hilft bei Regex“ löst nie aus. Schreib die Wörter, die der Nutzer tatsächlich eingibt, in seiner Sprache, und setze sie an den Anfang, wegen der weiter oben gemessenen Kürzung.

Ein SKILL.md mit zweitausend Zeilen. Der gesamte Hauptteil gelangt beim Auslösen in den Kontext. Die Spezifikation empfiehlt, unter 500 Zeilen zu bleiben und Details nach references/ auszulagern, das nur bei Bedarf geladen wird. Im obigen Test hat Codex cas-types.md erst geöffnet, als es seine Fälle schrieb.

Geheimnisse im Skill. Ein Skill wird geteilt, versioniert, veröffentlicht. Ein API-Schlüssel, der darin herumliegt, landet in einem öffentlichen Repository. Der Skill liest eine Umgebungsvariable, er enthält sie nicht.

Skills „für alle Fälle“ anhäufen. Jeder installierte Skill kürzt die Beschreibung aller anderen und nagt am Kontextfenster. Mach eine Bestandsaufnahme dessen, was nie ausgelöst hat, und entferne es.

Was du dir merken solltest

• Ein Skill = ein Ordner + eine SKILL.md (name höchstens 64 Zeichen, description höchstens 1.024) + was du sonst noch danebenlegen willst.
• Nur die Beschreibung wird dauerhaft geladen, und sie wird gekürzt: Die Auslösewörter gehören in die ersten 90 Zeichen.
• .agents/skills auf Projektebene, dazu .claude/skills, gelesen von Copilot und OpenCode: derselbe Ordner dient mehreren Agenten.
• Ein projektbezogener Skill lässt sich testen, ohne bei sich etwas zu installieren: <projet>/.codex/skills/ für Codex, <projet>/.claude/skills/ für Claude Code.
• Ein guter Skill erzwingt eine überprüfbare Prozedur und einen Exit-Code, keine Stilvorgabe.
• Lies jeden von einem Marktplatz installierten Skill vollständig: 13,4 % der von Snyk geprüften tragen einen kritischen Mangel.