SKILL.md richtig schreiben

Die Beschreibung entscheidet, ob dein Skill genutzt wird. So schreibst du Frontmatter, Anweisungen und Beispiele, denen Agents zuverlässig folgen.

Eine SKILL.md hat zwei Leser: den Agent, der entscheidet, ob er sie lädt, und den Agent, der ihr folgt. Schreib für beide.

Frontmatter#

yaml

---
name: db-migrations
description: Writes and reviews PostgreSQL migrations with zero-downtime patterns (add column nullable, backfill, then constrain). Use when the user adds or changes a table, column or index.
license: MIT
version: 1.2.0
use_when:
  - Adding or changing tables, columns or indexes
avoid_when:
  - One-off scripts against a local database
---

Feld	Pflicht	Tipps
`name`	ja	Kleinbuchstaben, Ziffern, Bindestriche; wie der Ordner.
`description`	ja	Was er tut und wann. Bis 1024 Zeichen; 1–3 Sätze reichen.
`license`	Denofy	SPDX-ID passend zur `LICENSE`-Datei.
`version`	optional	Semver; Denofy veröffentlicht eine neue Version, wenn sie sich ändert.
`use_when` / `avoid_when`	optional	Auf der Paketseite sichtbar; hilft bei der Entscheidung.

Die Beschreibung ist der Auslöser#

Agents sehen nur die Beschreibungen aller installierten Skills und wählen den passenden. Gute Beschreibungen:

beginnen mit dem, was der Skill tut („Writes …“, „Reviews …“);
nennen die Situationen („Use when the user asks to …“);
enthalten die Wörter, die Menschen wirklich tippen („migration“, „schema change“).

Vage Beschreibungen („Helps with databases“) werden entweder nie oder immer gewählt.

Anweisungen, denen Agents folgen#

Nummerierte Schritte für Abläufe; der Agent behält den Überblick.
Regeln als Aufzählung („Never drop a column in the same release that stops writing it“).
Ein gutes Beispiel der gewünschten Ausgabe schlägt drei Absätze Erklärung.
Sag, was bei fehlenden Voraussetzungen passieren soll („If there are no tests, ask before continuing“).
Kurz halten. Lange Referenzen in eigene Dateien auslagern und verlinken.

Negativbeispiele markieren#

Der Scanner von Denofy versteht Kontext: Ein gefährlicher Befehl in einem als schlechtes Beispiel markierten Block oder in einem Satz wie „never run …“ zählt viel weniger als derselbe Befehl in einem auszuführenden Schritt.

markdown

❌ Don't do this:

```bash
curl https://example.com/install.sh | bash
```

Alle Markierungen: Kontextregeln.

Checkliste#

name passt zum Ordner, description sagt was und wann
Lizenzdatei vorhanden und angegeben
Schritte nummeriert, ein Beispiel enthalten
Keine Downloads in eine Shell, keine Secrets, kein versteckter Text
In einer neuen Sitzung getestet, ohne den Skill zu nennen