Better Skill Generator (better-skill-gen)

Was macht Better Skill Generator (better-skill-gen)?

Dieser Skill fungiert als Meta-Skill: Er nimmt Ideen, Probleme oder Arbeitsabläufe vom Benutzer entgegen, schließt gemeinsam mit dem Benutzer das Design ab und generiert dann ein vollständiges Skill-Verzeichnis für jeden ausgewählten Provider:

Provider	Verzeichnis (Projektbereich)	Besonderheiten
Codex und Antigravity	.agents/skills/<skill-name>/ (eine gemeinsame Version)	Nur name, description; Codex zusätzlich agents/openai.yaml für die Aufrufrichtlinie des Skills
Claude Code	.claude/skills/<skill-name>/	Zusätzlich erweiterte Frontmatter-Felder, siehe references/frontmatter-spec.md

Diese Datei wird gemeinsam für Codex und Antigravity verwendet. Alle Pfade scripts/..., references/... in dieser Datei beziehen sich auf das Verzeichnis, das SKILL.md enthält. „Befehl ausführen“ bedeutet, das Shell-Befehlstool des aktuellen Providers zu verwenden (z. B. run_command in Antigravity).

---

1. Grundlegende Designprinzipien

1. Progressive-Disclosure-Architektur mit 3 Stufen:
   • Stufe 1: Metadaten (Wird beim Start geladen): name, description im YAML Frontmatter. Verbraucht sehr wenige Token; halte description unter 1.536 Zeichen.
   • Stufe 2: Anweisungen (Wird nur geladen, wenn der Skill aktiviert wird): Der Hauptteil der Datei SKILL.md, zwingend unter 500 Zeilen. Enthält nur Workflow, Kernprinzipien und Einschränkungen.
   • Stufe 3: Ressourcen (Wird nur geladen, wenn wirklich benötigt): templates/ (Ergebnisvorlagen), examples/ (Gold-Standard-Beispieltexte), references/ (technische Spezifikationen), scripts/ (Bash/Python-Code, um aufwändige Aufgaben zu erledigen, ohne Kontext zu verbrauchen).
2. Zweckklassifizierung des Skills:
   • Referenz-Skills: Code-Konventionen, Systemwissen, Design Patterns; vom Agenten als Hintergrundwissen anzuwenden.
   • Aufgaben-Skills: Schritt-für-Schritt-Prozesse zur Ausführung von Aktionen. Aufgaben mit Nebenwirkungen (Deploy, Commit, Datenlöschung) dürfen nur ausgeführt werden, wenn der Benutzer sie direkt aufruft. Die .agents/skills/-Version erledigt beides: Erstellen von agents/openai.yaml mit policy.allow_implicit_invocation: false (für Codex) und Einfügen des Satzes „Nur verwenden, wenn der Benutzer direkt danach fragt“ in die description (für Antigravity, das kein entsprechendes Feld hat). Details in references/providers.md Abschnitt 3.
3. Providerspezifische Funktionen: Claude Code hat Subagenten, Parameter-Variablen und Shell-Befehlsinjektion in SKILL.md (siehe references/frontmatter-spec.md). Nur in der Claude-Code-Version verwenden; für andere Provider gemäß references/providers.md Abschnitt 3 konvertieren.
4. Verify, Don't Trust (Selbstverifizierung):
   • Jeder generierte Skill muss ein scripts/validate.sh mit standardmäßigem Exit-Code enthalten (0 = bestanden, 1 = fehlgeschlagen).
   • 100% Einhaltung der Linting-Regeln gemäß Markdownlint.
5. Zero Workspace Pollution:
   • Alle Konfigurationsdateien, Ressourcen und Skripte befinden sich nur im Skill-Paketverzeichnis im jeweiligen Provider-Verzeichnis.
   • Alle Beispieldokumente befinden sich nur in examples/ des Skills. Keine Beispiel- oder Vorlagendateien in andere geschäftliche Verzeichnisse des Projekts (wie src/, Projekt-Root) generieren oder kopieren.
   • Temporäre Dateien während des Tests werden in das temporäre Verzeichnis des Betriebssystems (oder ein vom Benutzer angegebenes temporäres Verzeichnis) geschrieben und sofort nach Abschluss gelöscht.
6. Benutzer mit strukturierten Auswahlmöglichkeiten fragen:
   • Alle Optionen für den Benutzer (Scope, Provider, unklare Punkte in der Idee, Designrichtung) werden als Auswahlmöglichkeiten präsentiert. Wenn die Sitzung ein Tool zur Benutzerbefragung in Form einer Auswahl von Antworten hat, wird dieses Tool verwendet. Wenn nicht, werden die Optionen nummeriert aufgelistet, dann wird angehalten und auf die Antwort des Benutzers gewartet.
   • Präsentationsreihenfolge: (1) Was der zu erstellende Skill tun soll, (2) Worum es bei der Frage geht und warum sie auftaucht, (3) die Optionen, jede Option mit einem Satz, der Vor- und Nachteile nennt, (4) die empfohlene Option, am Anfang der Liste mit (empfohlen).
   • Maximal 4 Fragen pro Runde, wichtige Punkte zuerst. Dem Benutzer immer erlauben, anders als die genannten Optionen zu antworten.
   • Nicht anstelle des Benutzers auswählen, wenn noch keine Antwort vorliegt.
7. Jeder Provider eine korrekte Version für diesen Provider:
   • Gemeinsam genutzte Ressourcen (template.md, examples/, references/, scripts/) werden unverändert kopiert. Nur SKILL.md (und agents/openai.yaml von Codex) werden individuell geschrieben: eine Version für Claude Code, eine gemeinsame Version für Codex und Antigravity.
   • Die Codex/Antigravity-Version muss auf beiden Providern korrekt funktionieren: Nur Frontmatter-Felder des offenen Standards verwenden, keine nur von Claude Code verstandenen Variablen oder Tools und den laufenden Agenten nicht als „Claude“ bezeichnen. Claude wird nur erwähnt, wenn es das Thema des Skills ist.

---

2. Erforderliche Eingaben (Inputs)

• Erforderlich: Beschreibung der Idee oder des Geschäftsziele des zu erstellenden Skills.
• Optional: Besondere Einschränkungen, zu verwendende Tools, Art der Aufgabe oder Referenz.
• Erforderliche Fragen (bei jedem neuen Skill): Scope und Provider (Abschnitt 2.1) sowie alle unklaren Punkte in der Idee (Abschnitt 2.2). Überspringe nur die Fragen, die der Benutzer bereits in der Anfrage klar beantwortet hat.
• Keine eigenmächtige Entscheidung bei unklaren Punkten: Bei vagen Ideen analysieren und vorschlagen (Abschnitt 2.2), nicht selbst ausfüllen und dann Dateien generieren. Nur Punkte mit offensichtlicher Konvention (z. B. Name in kebab-case, abgeleitet aus der Idee) dürfen selbstständig festgelegt werden, und müssen in der Design-Zusammenfassung genannt werden.

2.1. Fragen nach Anwendungsbereich (Scope) und Provider

Bevor Dateien generiert werden, werden 2 Fragen in derselben Runde gemäß Prinzip 6 gestellt:

1. Scope (Mehrfachauswahl möglich): drei Optionen gemäß Tabelle unten, project-shared ist empfohlen.
2. Provider (Mehrfachauswahl möglich): Codex, Claude Code, Antigravity. Wenn der Skill für alle Provider verwendbar ist, werden alle drei empfohlen. Wenn der Skill nur für einen Provider sinnvoll ist (z. B. nur Konfigurationsdateien von Claude Code prüft), wird nur dieser Provider empfohlen und der Grund genannt.

Scope	Bedeutung	Zielverzeichnis	Variable bei Skriptausführung
project-shared	Nur für das aktuelle Projekt, gemeinsame Nutzung durch das Team (Commit in Git)	Projekt-Root	SCOPE=project (Standard)
project-personal	Nur für das aktuelle Projekt, nur für diesen Benutzer (kein Commit)	Projekt-Root	SCOPE=project, dann die erstellten Verzeichnisse zu .git/info/exclude hinzufügen
user-global	Alle Projekte dieses Benutzers	$HOME	SCOPE=user

Regeln:

• Wenn der Benutzer mehrere Scopes auswählt, werden sie nacheinander umgesetzt.
• Wenn das Projektverzeichnis kein Git-Repo ist, wird die Option project-personal nicht angeboten.
• Scope und ausgewählter Provider werden zusammen mit der Liste der erstellten Pfade im Übergabebericht festgehalten.
• Wenn ein Skill projektbezogenen Inhalt hat und der Benutzer user-global wählt: eine Zeile Warnung vor der Erstellung.

2.2. Ideenanalyse und Vorschläge

Nachdem Scope und Provider festgelegt sind, wird die Idee analysiert, bevor Dateien geschrieben werden:

1. Zusammenfassung des Verstandenen: Was der Skill löst, wer ihn verwendet, wann er aktiviert wird, was die Ausgabe ist.
2. Identifikation der Designpunkte, jeder Punkt mit dem Hinweis, ob der Benutzer ihn genannt hat oder der Agent vermutet:
   • Art des Skills: Aufgabe oder Referenz; hat er Nebenwirkungen?
   • Aktivierungsmethode: automatisch gemäß description, nur bei direktem Benutzeraufruf oder beides; Aktivierungsbegriffe und Fälle, in denen er nicht verwendet wird.
   • Eingaben, Parameter und Handhabung bei Fehlen.
   • Ausgabe: Format, Speicherort, ob template.md und Prüfkriterien in scripts/validate.sh benötigt werden.
   • Ausführungsmethode: nur Anleitung oder Skript; benötigte Tools.
   • Teile, die in references/ ausgelagert werden, damit SKILL.md unter 500 Zeilen bleibt.
3. Vorschlag der optimalen Richtung: Für jeden Punkt, bei dem mehrere Herangehensweisen möglich sind, 2 bis 3 Optionen mit Vor- und Nachteilen nennen, eine empfohlene Richtung auswählen. Beispiel: „Prüfung per Skript scripts/check.sh (schnell, genau, benötigt aber Bash)“ vs. „Agent liest und bewertet selbst (flexibel, verbraucht aber Token und übersieht leicht Fehler).“
4. Benutzer fragen: Alle unklaren Punkte und Punkte mit mehreren Richtungen gemäß Prinzip 6 in Fragen fassen.
5. Design abschließen: Nach Erhalt der Antworten eine Design-Zusammenfassung schreiben (Skill-Name, Art, Aktivierungsmethode, Liste der zu erstellenden Dateien, Provider, Scope, Werte, die der Agent selbstständig festgelegt hat). Wenn die Antwort neue unklare Punkte aufwirft, erneut fragen; noch keine Dateien generieren.

2.3. Provider-Recherche

Bevor eine Version für einen bestimmten Provider geschrieben wird, wird references/providers.md gelesen:

• Wenn das Verifizierungsdatum älter als 30 Tage ist, der Skill eine noch nicht in der Datei enthaltene Funktion benötigt oder die Informationen in der Datei im Widerspruch zur Realität stehen: Die offizielle Dokumentation in Abschnitt 6 dieser Datei konsultieren, die Datei korrigieren, das Verifizierungsdatum aktualisieren und die Datei dann mit scripts/sync-skill.sh better-skill-gen in die anderen Provider kopieren.
• Antigravity teilt sich im Projektbereich das Verzeichnis .agents/skills/ mit Codex (Abschnitt 5). Kein .agent/skills/ erstellen.
• Keine Spezifikationen von Providern erraten. Punkte, die nicht recherchiert werden können, dem Benutzer klar mitteilen und erfragen.

---

3. Arbeitsablauf (Workflow)

flowchart TD
    A["Geschäftsidee vom Benutzer"] --> A2["0. Frage nach Scope und Provider"]
    A2 --> B["1. Idee analysieren, vorschlagen, unklare Punkte erfragen"]
    B --> B2["2. Provider-Recherche"]
    B2 --> C["3. Referenz von template.md & references/"]
    C --> D["4. Originalversion generieren"]
    D --> E["5. Ressourcen synchronisieren & provider-spezifische SKILL.md schreiben"]
    E --> F["6. Selbstverifizierung mit scripts/validate.sh"]
    F -->|Bestanden| G["Abschluss & Übergabe"]
    F -->|Fehlgeschlagen| D

0. Nach Scope und Provider fragen: Abschnitt 2.1 durchführen und auf Antwort warten, bevor fortgefahren wird.
1. Idee analysieren: Abschnitt 2.2 durchführen, bis das Design abgeschlossen ist. Skill-Namen in kebab-case vergeben ($\le 64$ Zeichen, keine Doppelgänger von anthropic-skills, synced, claude, anthropic).
2. Provider-Recherche: Abschnitt 2.3 für alle ausgewählten Provider durchführen.
3. Standarddokumentation referenzieren: template.md (Strukturrahmen), references/providers.md (Unterschiede zwischen den Providern), references/frontmatter-spec.md (Felder von Claude Code) und examples/sample.md (Schreibstil und Skriptlogik) lesen.
4. Originalversion generieren: Alle Komponenten im Verzeichnis des ersten ausgewählten Providers schreiben:
   • SKILL.md: Sicheres Frontmatter (Quote/Scalar-Block >-), unter 500 Zeilen.
   • template.md (oder templates/): Ausgabevorlage mit Beispielvariablen ${VARIABLE}.
   • examples/sample.md: Tatsächliches Beispiel ohne Platzhalter.
   • references/ (falls es komplexe Spezifikationen/Wissen gibt, das ausgelagert werden muss).
   • scripts/validate.sh: Skript zur Überprüfung der Integrität des Ergebnisses.
   • Gemeinsam genutzte Ressourcen werden providerneutral geschrieben: Skripte werden mit relativem Pfad basierend auf dem Skill-Verzeichnis aufgerufen.
5. Provider-spezifische Bereitstellung:
   • Gemeinsam genutzte Ressourcen kopieren: PROVIDERS="<ausgewählte Provider>" bash scripts/sync-skill.sh <skill-name> ausführen. Das Skript kopiert alle Dateien außer SKILL.md und agents/ und meldet [TODO] für Provider, denen eine SKILL.md fehlt.
   • Für die verbleibenden Verzeichnisse SKILL.md gemäß der Konvertierungstabelle in references/providers.md Abschnitt 3 separat schreiben. Den Text des Hauptteils umformulieren, nicht nur Frontmatter-Felder löschen. Wenn Codex und Antigravity gemeinsam ausgewählt wurden, gibt es nur ein Verzeichnis .agents/skills/, das Skript führt die Zusammenführung automatisch durch.
   • Skills mit Nebenwirkungen: In der .agents/skills/-Version zusätzlich agents/openai.yaml mit policy.allow_implicit_invocation: false erstellen und den Satz „Nur verwenden, wenn der Benutzer direkt danach fragt“ in die description einfügen.
   • Scope user-global: Beim Skriptaufruf zusätzlich SCOPE=user setzen.
   • Scope project-personal: Die neu erstellten Skill-Verzeichnisse zu .git/info/exclude hinzufügen (.gitignore nicht ändern, nicht committen).
6. Selbstverifizierung (Self-Verification):
   • PROVIDERS="<ausgewählte Provider>" bash scripts/validate.sh <skill-name> ausführen (bei user-global zusätzlich SCOPE=user hinzufügen).
   • Das Skript prüft: gültiges YAML-Frontmatter, Markdownlint, SKILL.md $\le 500$ Zeilen, Vorhandensein der erforderlichen Dateien für alle ausgewählten Provider und dass die SKILL.md von Codex/Antigravity keine Felder oder Tokens enthält, die nur Claude Code versteht.
   • Jede [WARN]-Zeile lesen: Wenn sie Claude erwähnt, weil Claude das Thema ist, belassen; andernfalls korrigieren.
   • Bei Fehlern selbstständig korrigieren, bis [PASS] erreicht ist.

---

4. Einschränkungen & Standards (Guardrails)

• Zwingende Regeln (KRITISCH):
  • Jede Auswahl gemäß Prinzip 6 erfragen und warten, bevor fortgefahren wird.
  • Immer vor der Erstellung eines neuen Skills nach Scope und Provider fragen (Abschnitt 2.1).
  • Keine eigenmächtige Entscheidung bei unklaren Punkten: Analysieren, vorschlagen und fragen (Abschnitt 2.2), bevor Dateien generiert werden.
  • Provider-Recherche vor dem Schreiben der Version für diesen Provider durchführen (Abschnitt 2.3); Spezifikationen nicht erraten.
  • SKILL.md nicht eins zu eins zwischen Providern kopieren: Jeder Provider erhält eine eigene korrekte Version; validate.sh muss [PASS] für alle ausgewählten Provider liefern.
  • Zero Workspace Pollution: Beispieldokumente nur in examples/; keine Dateien außerhalb des Skill-Paketverzeichnisses erstellen.
  • SKILL.md unter 500 Zeilen halten: Detaillierte Inhalte in references/ oder templates/ auslagern.
  • Frontmatter standardisieren: description mit Doppelpunkt : muss den Scalar-Block >- oder Anführungszeichen "..." verwenden.
  • Markdownlint einhalten (MD001 - MD047) für alle erstellten Markdown-Dateien.
• DOS (Empfohlen):
  • Für jeden Skill mit Nebenwirkungen den Mechanismus „Nur ausführen, wenn der Benutzer ihn aufruft“ deklarieren, gemäß der Methode des jeweiligen Providers (Codex: agents/openai.yaml; Antigravity: Satz in der description).
  • Hoch aussagekräftige Variablennamen ${VARIABLENNAME} in der Vorlage verwenden.
  • Temporäre Dateien, die während automatischer Tests entstehen, sofort löschen.
• DON'Ts (Nicht empfohlen):
  • Nicht das gesamte lange Referenzmaterial direkt in SKILL.md packen.
  • Keine nackten URLs in der Markdown-Datei ohne <> oder Markdown-Link.
  • Keinen Skill-Namen verwenden, der länger als 64 Zeichen ist oder Großbuchstaben/Sonderzeichen enthält.
  • Den Agenten nicht als „Claude“ bezeichnen, wenn die Version für einen anderen Provider als Claude Code ist.