SNNN-011/skill-authoring

Skill Authoring

Leitfaden zum Erstellen eines Skills, der das Verhalten des Agenten tatsächlich verändert – kein Dokument, das nie gelesen wird.

Grundprinzip: Ein Skill ist eine operative Anweisung, kein Artikel. Wenn der Agent nach dem Laden dieses Skills nichts anders macht, ist der Skill gescheitert.

So verwenden Sie diesen Skill

Dieser Skill wird im Dialog verwendet, nicht einmalig. Der Ablauf:

1. Der Benutzer löst den Skill aus (z. B. „Verwende Skill skill-authoring, ich möchte einen Skill für meinen Agenten erstellen“).
2. Der Agent hört auf zu schreiben und beginnt mit dem Interview in Schritt 1: eine Frage pro Runde, warte auf die Antwort.
3. Nachdem alle fünf Fragen beantwortet sind, führt der Agent die Schritte 2 bis 5 aus und zeigt den Entwurf dem Benutzer.
4. Nach Zustimmung des Benutzers schreibt der Agent die Datei (Schritt 6), führt dann den Trigger-Test (Schritt 7) und die Checkliste (Schritt 8) aus.

Regeln für den Agenten:

• Schreibe SKILL.md nicht, bevor alle fünf Fragen aus Schritt 1 beantwortet sind. Ein vorzeitiger Entwurf stoppt das Interview.
• Stelle nicht alle fünf Fragen auf einmal. Eine pro Runde, mit einem kurzen Beispiel bei jeder Frage.
• Wenn der Benutzer nur ein „kurzes Beispiel“ möchte, stelle trotzdem die Fragen 1 und 4, und fahre dann fort.
• Sage zu Beginn, dass das Endergebnis eine einzelne Datei SKILL.md ist, die sofort verwendet werden kann.

Wann dieser Skill aktiv ist

• Der Benutzer sagt „Skill erstellen“, „Skill bauen“, „Wie erstelle ich einen Skill“, „Skill für meinen Agenten“.
• Der Benutzer hat eine Idee für eine Agentenfähigkeit, weiß aber nicht, wie er sie formulieren soll.
• Ein vorhandener Skill wird nie ausgelöst oder vom Agenten nicht befolgt.
• Es muss entschieden werden: Soll das ein Skill, Agent, Command oder Hook sein?

Um nach vorhandenen Skills zu suchen, verwende zuerst skill-scout. Um einen Stapel von Skills zu auditieren, verwende skill-stocktake.

Schritt 0 – Grundregeln vor dem Schreiben

Ein guter Skill hat vier Eigenschaften:

Eigenschaft	Bedeutung
Spezifisch	Beantwortet eine Art von Aufgabe, nicht „alles über Backend“
Operativ	Enthält Schritte, Befehle, konkrete Beispiele, keine Theorie
Auslösbar	Die description enthält Wörter, die der Benutzer tatsächlich verwendet
Begrenzt	Unter 500 Zeilen; idealerweise 100-250 Zeilen

Wenn die Skill-Idee diese vier nicht erfüllt, verbessere zuerst die Idee, schreibe keine Datei.

Schritt 1 – Erfasse das echte Problem, nicht die Funktion

Beginne nicht mit „Skill zum Testen“. Beginne mit einem konkreten Fehlschlag.

Stelle dem Benutzer diese fünf Fragen (eine nach der anderen, nicht alle auf einmal):

1. Was macht der Agent falsch oder inkonsistent? Gib ein konkretes Beispiel.
2. Wann passiert das? (Code schreiben, PR-Review, Deploy, Benutzerantworten, Datenanalyse)
3. Wie sieht das korrekte Ergebnis aus? Zeige ein Beispiel-Output, den der Benutzer für gut hält.
4. Welche Informationen weiß der Agent nicht und muss ihm durch diesen Skill mitgeteilt werden? (Teamkonventionen, Arbeitsschritte, Fallstricke)
5. Was darf der Agent nicht tun, während er diesen Skill ausführt?

Die Antworten auf Nummer 4 und 5 sind der eigentliche Inhalt des Skills. Die Antworten auf Nummer 1 und 2 sind der Inhalt der description.

Wenn der Benutzer Nummer 1 nicht beantworten kann, brich den Prozess ab. Es gibt noch keinen Skill zu erstellen – es gibt nur einen Wunsch. Sag das.

Schritt 2 – Wähle die richtige Form

Nicht alles sollte ein Skill sein. Wähle die günstigste Form, die das Problem löst.

Bedarf	Form	Grund
Wissen/Konventionen, die beim Schreiben von Code immer wieder verwendet werden	Skill	Wird automatisch geladen, muss nicht aufgerufen werden
Eigenständige, mehrschrittige Arbeit mit getrenntem Kontext	Agent	Kann parallel ausgeführt werden, hat eigenen Kontext
Aktion, die der Benutzer bewusst mit Argumenten auslöst	Command	/{name} explizit, nicht automatisch
Automatisches Verhalten bei Ereignissen (vor Commit, nach Bearbeitung)	Hook	Läuft ohne Entscheidung des Modells
Kurze Regel, die für alle Arbeiten gilt	Rule	Immer aktiv, ohne Auslöser
Lange Erklärung zum Lesen für Menschen	Dokument	Muss nicht vom Agenten geladen werden

Faustregel:

• Auslöser nötig? Skill.
• Getrennter Kontext oder eingeschränkte Tools nötig? Agent.
• Manuell mit Parametern aufrufbar nötig? Command.
• Soll ohne Aufforderung laufen? Hook.
• Soll immer richtig sein, nie verletzt werden? Rule.
• Soll von Menschen gelesen werden, nicht vom Agenten? Dokument.

Bei Zweifel zwischen Skill und Rule: Wenn der Inhalt weniger als 10 Zeilen hat und überall gilt, ist es eine Rule.

Schritt 3 – Suche zuerst nach Duplikaten

Bevor du schreibst, suche zuerst. Der Skill-Ordner unterscheidet sich pro Harness – passe ihn an den des Benutzers an:

Harness	Skill-Ordner
Claude Code	~/.claude/skills/ oder .claude/skills/ im Projekt
OpenCode	~/.config/opencode/skills/ oder .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# bereits installierte Skills (ersetze <skill-ordner> entsprechend der Tabelle oben)
grep -ril "stichwort" <skill-ordner> --include=SKILL.md

# wenn du dich in einem Repository mit einem skills/-Ordner befindest
grep -ril "stichwort" skills --include=SKILL.md

Wenn der Benutzer seinen Skill-Ordner nicht kennt, erkläre die obige Tabelle und bitte ihn, den verwendeten Harness auszuwählen. Rate nicht.

Wenn es bereits eine nahe Entsprechung gibt, wähle: verwende sie wie sie ist, erweitere die vorhandene oder erstelle eine neue. Doppelte Skills verwirren den Agenten bei der Auswahl und belasten den Kontext.

Schritt 4 – Schreibe die description (Der wichtigste Teil)

description ist der einzige Teil, den der Agent liest, um zu entscheiden, ob er den Skill lädt oder nicht. Ein Fehler hier bedeutet, dass der Skill tot ist.

Formel:

[Aktivität, die ausgeführt wird] + [Auslösekontext] + [Stichwörter, die der Benutzer verwendet] + [wann NICHT zu verwenden]

Schlechtes Beispiel:

description: Hilft beim Testen

Gutes Beispiel:

description: React-Testmuster mit Vitest und Testing Library – Rendern, Benutzerereignisse, Netzwerk-Mocking und Barrierefreiheits-Assertions. Verwenden beim Schreiben oder Reparieren von React-Komponententests. Nicht für E2E (verwende e2e-testing).

Regeln:

• Nenne Wörter, die der Benutzer tatsächlich eingibt, keine internen Begriffe.
• Nenne die Grenzen, damit der Skill nicht anderen Skills ins Handwerk pfuscht.
• Eine Zeile, keine Zeilenumbrüche innerhalb des Strings.
• Vermeide einzelne generische Wörter wie „Code“, „Hilfe“, „Verschiedenes“.

Schnelltest: Schließe die Datei, lies nur die description. Wenn du als Agent nicht genau weißt, wann du sie laden sollst, schreibe sie neu.

Schritt 5 – Gliedere den Inhalt

Eine Reihenfolge der Abschnitte, die sich bewährt hat:

---
name: skill-name
description: <Formel aus Schritt 4>
metadata:
  origin: ECC
---

# Titel

Ein Absatz: Was dieser Skill am Verhalten des Agenten ändert.

## Wann aktiv
Liste konkreter Auslöser.

## Kern
Arbeitsschritte, Entscheidungstabelle oder Regeln. Das sind 70 % des Skill-Inhalts.

## Beispiele
Ein falsches Beispiel, ein richtiges Beispiel. Real, kein Platzhalter.

## Anti-Pattern
Fehler, die vermieden werden sollten, mit kurzer Begründung.

## Checkliste
Kontrollkästchen, die überprüft werden können.

## Verwandte Skills
Zwei bis vier Skill-Namen.

Regeln zum Schreiben des Inhalts:

• Befehlssätze („Führe X aus“), keine passiven Beschreibungen („X kann ausgeführt werden“).
• Tabellen für Entscheidungen, nummerierte Listen für Reihenfolgen, Codeblöcke für Befehle.
• Jede Regel muss überprüfbar sein – „schreibe sauberen Code“ ist nicht überprüfbar, „Funktion maximal 50 Zeilen“ schon.
• Keine Platzhalter wie [hier einfügen], TODO oder ... in den Teilen, die der Agent ausführt.
• Keine direkt kopierten externen Produktidentitäten – nimm die Idee, schreibe sie im eigenen Kontext neu.
• Keine Geheimnisse: API-Schlüssel, Tokens, absolute private Pfade, interne Firmennamen.

Zeilenlängengrenze: 500 Zeilen (hartes Maximum 800). Bei mehr: teile den Skill in zwei auf oder verschiebe Details in references/ im selben Skill-Ordner.

Schritt 6 – Schreibe die Datei

Bevor du schreibst, stelle zwei letzte Fragen:

1. Skill-Sprache – die Sprache, die der Benutzer im Alltag verwendet, oder Englisch für Portabilität? Folge der Antwort, wähle nicht einfach so.
2. Ordnername – schlage einen beschreibenden Namen in Kebab-Schreibweise vor (z. B. test-komponenten-react), bitte um Zustimmung.

Schreibe dann in <skill-ordner>/<name>/SKILL.md. Regeln, die nicht verletzt werden dürfen:

• name: im Frontmatter muss exakt mit dem Ordnernamen übereinstimmen. Ohne dies verweigern einige Harness das Laden des Skills.
• Zeige dem Benutzer zuerst den vollständigen Entwurf, bevor du speicherst. Speichere nicht stillschweigend.
• Keine Platzhalter (TODO, [hier einfügen], ...) in den Teilen, die der Agent ausführen wird.
• Melde nach dem Speichern den vollständigen Pfad und einen Satz zur Auslösung: „Bitte den Agenten bitten, den Skill <name> bei <Auslöser> zu verwenden.“

Schritt 7 – Teste vor der Verwendung

Drei Mindesttests. Überspringe keinen.

Test 1 – Positiver Trigger (einschalten) Gib dem Agenten eine Aufgabe, die diesen Skill auslösen sollte, ohne den Skill-Namen zu nennen.

"Bitte schreibe einen Test für die LoginButton-Komponente."

Bestanden, wenn der Skill geladen wird. Nicht bestanden bedeutet, dass der description Schlüsselwörter fehlen.

Test 2 – Negativer Trigger (nicht einschalten) Gib eine ähnliche, aber nicht zur Domäne gehörende Aufgabe.

"Bitte schreibe einen E2E-Test für den Login-Ablauf."

Bestanden, wenn der Skill NICHT geladen wird (oder der Agent einen anderen, passenden Skill wählt). Nicht bestanden bedeutet, dass die description zu weit gefasst ist.

Test 3 – Ausführung Bitte den Agenten, eine Aufgabe zu erledigen, die den Skill wirklich auslöst, und vergleiche die Ausgabe mit der ohne Skill.

Ohne Skill: Agent schreibt Test im Stil X
Mit Skill: Agent schreibt Test im Stil Y (gemäß Teamkonvention)

Bestanden, wenn ein Unterschied im Verhalten nachweisbar ist. Wenn die Ausgabe identisch ist, ist der Skill nutzlos – lösche ihn oder führe ihn zusammen.

Schritt 8 – Checkliste versandbereit

• Datei befindet sich in <skill-ordner>/{name}/SKILL.md, und name: stimmt exakt mit dem Ordnernamen überein
• description ist eine Zeile, enthält die Stichwörter des Benutzers und die Bereichsgrenzen
• description verwendet keinen Literalblock (|), nur einen Inline-String
• Es gibt einen expliziten Abschnitt „Wann aktiv“
• Jede Regel ist überprüfbar, kein „schreibe guten Code“
• Es gibt mindestens ein falsches und ein richtiges Beispiel
• Es gibt ein Anti-Pattern
• Unter 500 Zeilen
• Keine Geheimnisse, Tokens oder absoluten privaten Pfade
• Tests 1, 2 und 3 wurden durchgeführt und die Ergebnisse dokumentiert
• Schritt 3 wurde durchgeführt, keine Duplikate vorhanden
• Am Ende werden 2-4 verwandte Skills genannt

Automatische Validierung nur, wenn im Repository des Benutzers verfügbar:

# ECC / Repository mit Skill-Validator
node scripts/ci/validate-skills.js

Wenn kein Validator vorhanden ist, überprüfe manuell die vier häufigsten Fehler: name: stimmt mit Ordner überein, description ist eine Zeile, Zeilen unter 500, und keine Platzhalter. Teile dem Benutzer mit, dass diese manuelle Prüfung verwendet wird.

Gebrauchsfertige Vorlage

---
name: skill-name
description: <Aktivität> - <Bereich>. Verwenden bei <konkreter Auslöser>. Nicht für <außerhalb des Bereichs>.
metadata:
  origin: ECC
---

# Skill-Name

Was sich am Verhalten des Agenten ändert, nachdem dieser Skill geladen wurde.

## Wann aktiv
- <Auslöser 1>
- <Auslöser 2>

## Schritte
1. <erster Schritt, der sofort ausgeführt werden kann>
2. <zweiter Schritt>
3. <Überprüfung>

## Beispiele
Falsch: <Code oder Antwort, die häufig vorkommt>
Richtig: <gewünschte Version, mit kurzer Begründung>

## Anti-Pattern
- <Fehler> - <warum schlecht>

## Checkliste
- [ ] <was maschinell oder mit bloßem Auge überprüft werden kann>

## Verwandte Skills
- `<skill-a>`, `<skill-b>`

Anti-Pattern Authoring

• Skill ohne Auslöser. description vage, Skill wird nie geladen. Dies ist die häufigste Ursache für Fehlschläge.
• Skill als Textwand. 900 Zeilen Theorie ohne einen einzigen Befehl. Der Agent lädt ihn und ignoriert ihn.
• Skill „Sei hilfreich“. Ohne spezifisches Wissen ist das Ergebnis identisch mit dem ohne Skill.
• Doppelter Skill. Zwei Skills beanspruchen dieselbe Domäne; der Agent wählt zufällig.
• Komplettes Kopieren eines fremden Skills. Enthält versteckte Anweisungen und Abhängigkeiten, die du nicht bemerkst.
• Skill mit Geheimnissen oder privaten Pfaden. Verbreitet sich, wenn der Skill geteilt wird.
• Skill für ein einzelnes Ereignis schreiben. Wenn er nur einmal verwendet wird, ist es kein Skill – es ist Dokumentation oder ein Command.
• Skill erstellen, bevor gesucht wird. Führe immer Schritt 3 aus.

Wann KEIN Skill erstellt werden muss

Sage dem Benutzer direkt, wenn einer dieser Punkte zutrifft:

• Das Problem ist ein Bug im Code, nicht fehlendes Wissen des Agenten.
• Es wird nur einmal benötigt – gib einfach eine direkte Anweisung.
• Der Inhalt besteht aus weniger als 10 Zeilen allgemeiner Regeln – das ist eine Rule.
• Es reicht, es zu AGENTS.md oder CLAUDE.md des Projekts hinzuzufügen.
• Es gibt bereits einen Skill, der 80 % des Bedarfs abdeckt – erweitere den vorhandenen.

Verwandte Skills

• skill-scout – sucht nach vorhandenen Skills, bevor ein neuer erstellt wird
• skill-stocktake – auditieren der Qualität eines Skill-Stapels
• skill-comply – misst, ob der Skill wirklich vom Agenten befolgt wird
• agent-harness-construction – entwirft Tools und Aktionsgrenzen für Agenten