Zum Hauptinhalt springen

SKILL.md: Der agentenübergreifende offene Standard

Fortgeschritten

Ein paar Jahre lang hatte jeder Coding-Agent seine eigene Datei: .cursorrules, CLAUDE.md, Codex-System-Prompts, Gemini-Instruktionen, ein Dutzend mehr. Dann machte Anthropic still ihr internes Skills-Format zu einer offenen Spezifikation — und innerhalb von 48 Stunden lasen die größten Agenten der Welt die Dateien der jeweils anderen. Heute läuft ein Verzeichnis namens code-reviewer/ mit einer SKILL.md darin unverändert in Claude Code, Codex CLI, ChatGPT, Gemini CLI, Junie, Kiro, Goose und Cursor. Das ist der Agentenwelt am nächsten an einem gemeinsamen Stecker gekommen.

Diese Seite ist der praktische Feldführer: was der Standard auf Byte-Ebene tatsächlich ist, der eine clevere Trick (Progressive Disclosure), der 100-Skill-Installationen günstig macht, genau welche Felder Portabilität in dem Moment brechen, in dem du sie anfasst, das ehrliche Sicherheitsbild und ein kopierbarer portabler Skill, den du heute ausliefern kannst.

What you'll learn
  • Verstehe, was SKILL.md auf Dateiformat-Ebene ist — Pflichtfelder, optionale Felder, Verzeichnislayout
  • Verstehe Progressive Disclosure: warum 100 Skills beim Start ~10K Tokens kosten, nicht 100× den Body
  • Kenne die genauen Anbieter-Erweiterungen, die Portabilität zwischen Agenten still brechen
  • Schreibe einen Skill, der unverändert in Claude Code, Codex CLI und Gemini CLI läuft
  • Wäge die Sicherheitsabwägung ehrlich ab, bevor du Skills aus irgendeinem Marktplatz installierst

Was der Standard tatsächlich ist​

Zieh das Marketing ab, und der offene Standard für Agent Skills ist klein genug, ihn im Kopf zu behalten:

  • Ein Verzeichnis, dessen Name der name des Skills ist
  • Eine erforderliche SKILL.md-Datei darin — YAML-Frontmatter, dann Markdown-Body
  • Optionale Geschwister: scripts/ (Executables, die der Skill ausführen kann), references/ (Docs, die der Skill on demand hinzuzieht), assets/ (Templates, Bilder, Prompt-Dateien) und — später hinzugefügt — agents/ für Opt-in-anbieterspezifische Config

Das ist die gesamte Oberfläche. Zwei Pflicht-Frontmatter-Felder machen den Großteil der Arbeit:

  • name — bis zu 64 Zeichen, lowercase-with-hyphens, muss dem Elternverzeichnis entsprechen
  • description — bis zu 1.024 Zeichen, der Satz, mit dem der Agent entscheidet, ob dieser Skill für die aktuelle Aufgabe geladen wird

Alles andere — license, compatibility, metadata und das noch experimentelle allowed-tools — ist optional und wird von Tools, die es nicht verstehen, sicher ignoriert. Bodies sind Markdown; die Community-Konvention ist, sie unter ~5.000 Tokens zu halten, und reale Skills tun das meist: die mediane Skill-Größe im größten Marktplatz liegt bei etwa 1.414 Tokens, 90% unter 3.935 Tokens.

Der eine clevere Trick: Progressive Disclosure​

Der Grund, warum SKILL.md im Maßstab funktioniert, ist nicht das Dateiformat — sondern wie Agenten es laden. Alle konformen Agenten implementieren drei Stufen:

Guided walkthrough1 of 3
  1. Der Agent geht das Skills-Verzeichnis durch und liest nur das Frontmatter jeder SKILL.md. Das sind grob 100 Tokens pro Skill. Installiere 100 Skills und du hast ~10K Tokens Kontext vor deinem ersten Prompt verbraucht — günstiger als eine einzelne lange System-Message.

Deshalb kappt die Spec description so eng und behandelt sie als First-Class-Feld: es ist der einzige Text, den das Modell sieht, wenn es entscheidet, ob der Skill aktiviert wird. Eine vage Beschreibung ist der häufigste Grund, warum ein Skill, der "eigentlich funktionieren sollte", nie feuert.

:::tip Schreib die Beschreibung zuletzt und schreib sie um Wenn der Body eines Skills solide ist, geh zurück und behandle die Beschreibung als deine Werbekopie. Sie hat einen Job: dem Modell helfen, die Form einer Aufgabe zu erkennen, die dieser Skill übernehmen sollte. "Reviewt Pull Requests" ist schlecht. "Reviewt einen PR-Diff auf Logik-Bugs, fehlende Tests und verletzte Projekt-Konventionen; verwende, wann immer der Nutzer nach einem Review, Code-Review oder 'schau dir diesen PR an' fragt" ist gut. :::

Das universelle Verzeichnis​

Jeder konforme Agent erwartet dasselbe Layout. Dieses funktioniert überall:

code-reviewer/
├── SKILL.md          # required — the instructions the agent reads
├── scripts/          # optional — executables the skill can invoke
│   └── run-linters.sh
├── references/       # optional — long docs the skill pulls on demand
│   └── style-guide.md
├── assets/           # optional — templates, prompt files, snippets
│   └── pr-comment-template.md
└── agents/           # optional — VENDOR-SPECIFIC, opt-in only
    └── openai.yaml   # ignored by every non-Codex agent

Das agents/-Unterverzeichnis ist das Sicherheitsventil des Standards: es erlaubt Anbietern, Erweiterungen auszuliefern, ohne den portablen Kern zu kontaminieren. Eine Datei bei agents/openai.yaml ist Codex-spezifisch und jeder andere Agent ignoriert sie einfach. Nutze es, wenn du zusätzliche Kraft brauchst; wisse, es kostet dich Portabilität.

Was tatsächlich reist vs. was still nicht​

Die ganze Spec wurde für Portabilität entworfen, aber reale Skills in freier Wildbahn haben drei Failure-Modes.

Was du nutztPortabel?Warum
name, description, Markdown-Body✅ JaKern-Spec. Jeder konforme Agent liest diese identisch.
scripts/, references/, assets/, vom Body referenziert✅ JaVerzeichnislayout ist Teil der Spec; Agenten lesen sie, wenn der Body es sagt.
license, metadata✅ Ja (sicher zu ignorieren)Optionale Felder — nicht unterstützende Agenten überspringen ohne Fehler.
allowed-tools-Frontmatter⚠️ TeilweiseIn der Spec als experimentell markiert; Syntax zwischen Agenten nicht standardisiert. Claude Code honoriert eine Form, Codex CLI eine andere, die meisten anderen ignorieren es ganz.
Claude Codes when_to_use-Liste❌ Nur ClaudeStill ignoriert von Codex, Gemini CLI und allen anderen.
Claude Codes context: fork-Subagent-Flag❌ Nur ClaudeNicht portable Subagent-Ausführungssemantik — Modellverhalten unterscheidet sich überall sonst.
agents/openai.yaml-Erweiterungen❌ Nur CodexExplizit anbieter-scoped by design. Portabel weil andere Agenten es ignorieren.

Die Lektion ist unverblümt: halte dich an name + description + Markdown-Body + die drei optionalen Unterverzeichnisse, und dein Skill läuft überall. Greif nach irgendeinem Frontmatter-Feld jenseits der zwei Kernfelder, und du baust für einen Agenten. Das ist eine legitime Wahl — manche Skills brauchen es wirklich — aber tu es bewusst, nicht weil du ein Template kopiert hast.

Wie Aktivierung tatsächlich funktioniert (pro Agent)​

Die Spec standardisiert die Datei, nicht die Entscheidung. Jeder Agent führt weiter seine eigene Aktivierungslogik auf den Beschreibungen aus, die er beim Start las:

  • Claude Code matcht die Lesart des Modells der aktuellen Runde gegen description und (falls vorhanden) die Claude-spezifische when_to_use-Liste; Aktivierung ist eine Modell-Entscheidung, keine Keyword-Regel.
  • Codex CLI nutzt dieselbe beschreibungs-getriebene Aktivierung mit optionalen Overrides in agents/openai.yaml.
  • Gemini CLI lädt ebenfalls Beschreibungen beim Start und lässt Gemini wählen; Verhalten folgt Geminis eigenen Tool-Auswahl-Heuristiken.
  • Cursor, Junie, Kiro, Goose implementieren alle beschreibungs-getriebene Aktivierung mit leichten Variationen in der Gewichtung.

Praktische Konsequenz: ein Skill, der auf einem Agenten nie feuert, aber auf einem anderen funktioniert, hat fast immer ein Beschreibungsproblem, nicht ein Body-Problem. Schreibe die Beschreibung so um, dass sie die Form der Nutzeranfrage beschreibt, nicht die Interna des Skills, und die Feuerrate steigt auf jedem Agenten gleichzeitig.

Eine portable SKILL.md zum Kopieren​

Hier ist ein minimaler, tatsächlich portabler Code-Review-Skill. Leg ihn nach ~/.agents/skills/code-reviewer/SKILL.md und er läuft ohne Modifikation in Claude Code, Codex CLI, ChatGPT und Gemini CLI.

code-reviewer/SKILL.md

---
name: code-reviewer
description: Reviews a diff or pull request for logic bugs, security issues, missing tests, and violations of project conventions. Use whenever the user asks for a review, code review, PR review, or "look at this diff / patch / change".
license: MIT
---

# Code Reviewer

You review code changes with the discipline of a staff engineer who cares
about the codebase surviving contact with reality. You are opinionated but
short. You never restate what the diff does — the user can read it.

## What to look at

1. **Logic bugs** — off-by-one, wrong operator, swapped arguments, unhandled
 error path, race, silent catch.
2. **Missing tests** — any changed behavior without a test is a finding.
3. **Security** — injection, secrets, missing auth checks, unsafe deserialization,
 unbounded input.
4. **Project conventions** — if a CLAUDE.md, AGENTS.md, .cursorrules, or README
 exists in the repo root, load it and enforce what it says.
5. **Complexity that will hurt future readers** — call it out, propose the
 simpler shape.

## What NOT to do

- Do not comment on formatting the linter will catch.
- Do not praise. No "great work" / "nice refactor".
- Do not summarize the diff. Assume the reader read it.

## Output format

For each finding, one line:

`path:line — <severity>: <problem>. <concrete fix>.`

Severities: 🔴 blocker, 🟠 important, 🟡 nit.

End with a one-line verdict: "ship", "ship with fixes", or "rework".

Jede Zeile dieses Skills läuft auf jedem konformen Agenten. Nichts im Frontmatter ist anbieter-scoped. Der Body nutzt einfache Markdown-Headings, die jeder Agent parst.

Vergleich zu einer nicht-portablen Variante — subtil, sie ist nur Claude:

Nur-Claude-Variante (nicht nutzen, wenn du Portabilität willst)

---
name: code-reviewer
description: Reviews a diff or pull request.
when_to_use:
- user asks for a review
- user pastes a diff
context: fork
allowed-tools: [Bash, Read, Grep]
---

Drei Dinge brechen Portabilität auf einmal: when_to_use (nur Claude Code), context: fork (Claude-Code-Subagent-Semantik) und allowed-tools (experimentell, nicht konsistent honoriert). Codex liest die Beschreibung als "Reviews a diff or pull request" — was so vage ist, dass sie kaum jemals aktiviert wird — und ignoriert den Rest.

Das Sicherheitsbild (sei ehrlich zu dir selbst)​

Die unbequeme Wahrheit über das Installieren von Skills aus jedem Marktplatz: ein Skill ist eine beliebige Instruktion an einen hochfähigen Agenten, der in deiner Umgebung mit deinen Berechtigungen läuft. Der Standard spezifiziert kein Code Signing, kein Sandboxing, kein verpflichtendes Review und kein Laufzeit-Berechtigungsmodell. Es ist by design eine Textdatei-Spec, keine Sicherheits-Spec.

Die konkreten Zahlen, aus unabhängigen Analysen großer öffentlicher Skill-Kataloge (an der Quelle bestätigen, bevor zitieren):

  • Grob eine von drei öffentlich geteilten Skills enthält mindestens einen sicherheitsrelevanten Mangel — zu breite Shell-Anweisungen, hartkodierte Secrets, Aufrufe an untrusted URLs oder curl | sh-artige Bootstrap-Schritte.
  • Eine kleinere, aber nicht-null Menge von Skills wurde als offen bösartig markiert — Versuche der Exfiltration, Credential-Harvesting oder destruktiven Operationen.
  • Skills erben, was der Agent erbt. Kann dein Agent ~/.ssh/ lesen, kann jeder Skill, den du installierst, es auch.

Praktische Verteidigungen, die tatsächlich funktionieren:

Guided walkthrough1 of 4
  1. Es ist Markdown. Es dauert eine Minute. Wenn die Beschreibung sagt 'formatiert Prosa' und der Body ein `curl` zu einer URL enthält, die du nicht erkennst, ist das der Moment, wo du aufhörst.

Für eine tiefere Betrachtung, wie Skills kompromittiert werden und was zu prüfen ist, siehe Vetting Agent Skills und Coding Agents Under Attack.

Wann einen Skill schreiben vs. wann einfach prompten​

Neue Maintainer eines Skill-Katalogs überproduzieren sie oft. Eine nützliche Regel:

  • Prompt für eine einmalige Aufgabe oder eine Form, die du in einem Projekt nutzt. Skills tragen Startkosten — auch wenn klein — und clutter dein Description-Budget.
  • Schreibe einen Skill, wenn dieselben Anweisungen über viele Chats oder Projekte gelten (Code-Review, Commit-Message-Schreiben, Changelog-Generierung, Rechnungsextraktion) und die Beschreibung eindeutig wäre. Kannst du keine knackige Beschreibung schreiben, feuert der Skill sowieso nicht zuverlässig.
  • Greif stattdessen zu einem Subagenten, wenn die Aufgabe ihr eigenes Tool-Set, ihre eigene Modellwahl oder echte Parallelität braucht. Skills instruieren das Haupt-Modell; Subagenten laufen separat. Siehe Subagenten.

Verwandte Lektüre​

Prüfe deinen Griff​

Check yourself

0/4
  1. Du installierst 100 Skills. Ungefähr wie viele Tokens kosten ihre Beschreibungen deinen Agenten beim Start?
  2. Welches dieser Frontmatter-Felder bricht deinen Skill still auf Codex CLI und Gemini CLI, obwohl es in Claude Code funktioniert?
  3. Ein Skill, den du schriebst, feuert zuverlässig auf Claude Code, aber fast nie auf Codex CLI. Was ist das leverage-stärkste, das zuerst zu fixen ist?
  4. Warum ist die Sicherheitshaltung von Agent Skills fundamental schwächer als etwa npm-Pakete mit Lockfiles und Audit-Tooling?

Quellen & weiterführende Lektüre​