Die Kurzantwort
Funktioniert der Aufruf über den Namen, ist der Skill installiert. Ob er von selbst startet, hängt von seiner Beschreibung ab, die der Agent zuerst liest und eventuell kürzt. Teste beides getrennt, denn sie scheitern aus unterschiedlichen Gründen.
Wie jeder Agent einen Skill auswählt
Jeder Agent liest zuerst eine Liste mit Skill-Namen und -Beschreibungen und lädt die vollständigen Anweisungen erst, nachdem er einen gewählt hat. Diese Liste stammt aus dem Frontmatter jeder SKILL.md (der Datei, nach der viele als skills.md suchen), und sie hat ein Größenbudget:
| Agent | Liest zuerst | Wenn der Platz ausgeht |
|---|---|---|
| Claude Code | Name und Beschreibung, dazu when_to_use, falls gesetzt; jeweils bis zu 1.536 Zeichen | Die Liste bekommt etwa 1 % des Kontextfensters; die am seltensten genutzten Beschreibungen fallen zuerst weg |
| Codex | Name, Beschreibung und Dateipfad | Die Liste bekommt etwa 2 % des Kontextfensters; Beschreibungen werden zuerst gekürzt |
| Cursor | Name und Beschreibung | Nicht dokumentiert |
Bei vielen installierten Skills kann eine lange oder vage Beschreibung gekürzt oder gestrichen werden, bevor der Agent sie überhaupt abwägt. Deshalb zählt der erste Satz am meisten.
Eine Skill-Beschreibung schreiben, die gewählt wird
Schreib die Beschreibung so, wie eine Kollegin die Arbeit anfragen würde, und stell den Hauptzweck in den ersten Satz.
Der Agent gleicht deine Anfrage mit diesen Wörtern ab – nutze also die, die Leute tatsächlich tippen, etwa „landing page“, „Launch-Seite“ oder „Pitch Deck“. Nenn zuerst das Ergebnis und sag dann, wann der Skill gebraucht wird.
Was er macht und wann
- „Build a product launch page with a hero, feature grid, and pricing toggle. Use when asked for a landing or launch page.“
Generisch
- „Helps with websites.“
- Konkurriert mit jedem anderen Web-Skill und sagt gekürzt fast nichts mehr.
So testest du, ob er auslöst
Teste in dieser Reihenfolge. Der erste Schritt schließt ein Installationsproblem aus, alles, was danach scheitert, liegt also an der Beschreibung.
- 1Ruf ihn über den Namen auf. Klappt das nicht, ist es ein Installationsproblem; siehe Fehlerbehebung.
- 2Starte eine neue Sitzung, damit der frühere Aufruf nicht im Kontext ist, und frag mit normalen Worten ohne den Namen.
- 3Frag den Agent, welchen Skill er genutzt hat, und prüf dann eine Anweisung, die nur dieser Skill befolgen würde.
Wenn der falsche Skill läuft
Meist überschneiden sich zwei Beschreibungen, oder derselbe Skill ist zweimal installiert.
- Ruf den gewünschten Skill über den Namen auf. Ein Aufruf über den Namen gewinnt immer.
- Grenz überlappende Beschreibungen über Eingabe, Zielgruppe oder Ergebnis ein, sodass jeder Skill eine klare Aufgabe hat.
- Gleicher Name an zwei Orten: Claude Code bevorzugt Enterprise, dann persönlich, dann Projekt. Codex listet eventuell beide. Behalte nur eine Kopie.
Häufige Fragen
Warum löst mein Claude Skill nicht aus?
Ruf ihn zuerst über den Namen auf. Klappt das nicht, ist der Skill nicht dort installiert, wo der Agent sucht; scheitern nur normale Anfragen, schreib die Beschreibung mit den Wörtern neu, die du tatsächlich tippst.
Wie entscheidet Claude, welchen Skill es nutzt?
Es liest Name und Beschreibung jedes Skills und lädt den, der am besten zu deiner Anfrage passt. Mit /skill-name entfällt dieser Abgleich, und der genannte Skill läuft.
Was sollte in einer Skill-Beschreibung stehen?
Was der Skill erstellt und wann er gebraucht wird, mit dem Hauptzweck im ersten Satz. Nutze die Wörter, die Leute tatsächlich tippen, etwa „landing page“ oder „Pitch Deck“, denn die Beschreibung wird eventuell gekürzt.
Heißt die Datei SKILL.md oder skills.md?
Sie heißt SKILL.md, eine pro Skill-Ordner. Ihr Frontmatter enthält Name und Beschreibung, die Agents bei der Wahl eines Skills lesen.
Quellen
War diese Anleitung hilfreich?