skill-creator

Skill Creator

Diese Skill bietet Anleitung zur Erstellung effektiver Skills.

Über Skills

Skills sind modulare, eigenständige Ordner, die die Fähigkeiten von Codex erweitern, indem sie spezialisiertes Wissen, Workflows und Werkzeuge bereitstellen. Stellen Sie sie sich als "Onboarding-Leitfäden" für bestimmte Domänen oder Aufgaben vor – sie verwandeln Codex von einem universellen Assistenten in einen spezialisierten Agenten, der mit prozeduralem Wissen ausgestattet ist, das kein Modell vollständig besitzen kann.

Was Skills bieten

1. Spezialisierte Workflows – Mehrschrittige Verfahren für bestimmte Domänen
2. Tool-Integrationen – Anweisungen für die Arbeit mit bestimmten Dateiformaten oder APIs
3. Domänenexpertise – Unternehmensspezifisches Wissen, Schemata, Geschäftslogik
4. Gebündelte Ressourcen – Skripte, Referenzen und Assets für komplexe und sich wiederholende Aufgaben

Kernprinzipien

Prägnanz ist entscheidend

Der Kontextfenster ist ein Gemeinschaftsgut. Skills teilen sich den Kontextfenster mit allem, was Codex sonst noch benötigt: System-Prompt, Konversationsverlauf, Metadaten anderer Skills und die eigentliche Benutzeranfrage.

Standardannahme: Codex ist bereits sehr intelligent. Fügen Sie nur Kontext hinzu, den Codex noch nicht hat. Hinterfragen Sie jede Information: "Braucht Codex diese Erklärung wirklich?" und "Rechtfertigt dieser Absatz seine Token-Kosten?"

Bevorzugen Sie prägnante Beispiele gegenüber ausführlichen Erklärungen.

Angemessene Freiheitsgrade setzen

Passen Sie den Spezifitätsgrad an die Fragilität und Variabilität der Aufgabe an:

• Hohe Freiheit (textbasierte Anweisungen): Verwenden, wenn mehrere Ansätze gültig sind, Entscheidungen vom Kontext abhängen oder Heuristiken den Ansatz leiten.
• Mittlere Freiheit (Pseudocode oder Skripte mit Parametern): Verwenden, wenn ein bevorzugtes Muster existiert, Abweichungen akzeptabel sind oder die Konfiguration das Verhalten beeinflusst.
• Niedrige Freiheit (spezifische Skripte, wenige Parameter): Verwenden, wenn Operationen fragil und fehleranfällig sind, Konsistenz kritisch ist oder eine bestimmte Reihenfolge eingehalten werden muss.

Stellen Sie sich Codex vor, der einen Pfad erkundet: Eine schmale Brücke mit Klippen benötigt spezifische Geländer (niedrige Freiheit), während ein offenes Feld viele Routen erlaubt (hohe Freiheit).

Validierungsintegrität schützen

Sie können während der Iteration Subagenten zur Validierung einsetzen, um zu prüfen, ob eine Fertigkeit bei realistischen Aufgaben funktioniert oder ob ein vermutetes Problem real ist. Dies ist am nützlichsten, wenn Sie nach einer Überarbeitung einen unabhängigen Prüfdurchlauf zum Verhalten, den Ausgaben oder den Fehlermodi der Fertigkeit wünschen. Tun Sie dies nur, wenn es möglich ist, neue Subagenten zu starten.

Wenn Sie Subagenten zur Validierung verwenden, behandeln Sie dies als Evaluierungsoberfläche. Ziel ist es zu erfahren, ob die Fertigkeit verallgemeinert, nicht ob ein anderer Agent die Antwort aus durchgesickertem Kontext rekonstruieren kann.

Bevorzugen Sie rohe Artefakte wie Beispiel-Prompts, Ausgaben, Diffs, Logs oder Traces. Geben Sie den minimalen aufgabenlokalen Kontext, der zur Durchführung der Validierung benötigt wird. Vermeiden Sie es, die beabsichtigte Antwort, den vermuteten Fehler, die beabsichtigte Korrektur oder Ihre vorherigen Schlussfolgerungen weiterzugeben, es sei denn, die Validierung erfordert diese explizit.

Anatomie einer Fertigkeit

Jede Fertigkeit besteht aus einer erforderlichen SKILL.md-Datei und optionalen gebündelten Ressourcen:

fertigkeitsname/
├── SKILL.md (erforderlich)
│   ├── YAML-Frontmatter-Metadaten (erforderlich)
│   │   ├── name: (erforderlich)
│   │   └── description: (erforderlich)
│   └── Markdown-Anweisungen (erforderlich)
├── agents/ (empfohlen)
│   └── openai.yaml – UI-Metadaten für Fertigkeitslisten und Chips
└── Gebündelte Ressourcen (optional)
    ├── scripts/          – Ausführbarer Code (Python/Bash/etc.)
    ├── references/       – Dokumentation, die bei Bedarf in den Kontext geladen werden soll
    └── assets/           – In der Ausgabe verwendete Dateien (Vorlagen, Symbole, Schriftarten usw.)

SKILL.md (erforderlich)

Jede SKILL.md besteht aus:

• Frontmatter (YAML): Enthält die Felder name und description. Dies sind die einzigen Felder, die Codex liest, um zu bestimmen, wann die Fertigkeit verwendet wird, daher ist es sehr wichtig, klar und umfassend zu beschreiben, was die Fertigkeit ist und wann sie verwendet werden sollte.
• Body (Markdown): Anweisungen und Anleitung zur Verwendung der Fertigkeit. Wird erst geladen, NACHDEM die Fertigkeit ausgelöst wird (falls überhaupt).

Agents-Metadaten (empfohlen)

• UI-orientierte Metadaten für Fertigkeitslisten und Chips
• Lesen Sie references/openai_yaml.md, bevor Sie Werte generieren, und befolgen Sie dessen Beschreibungen und Einschränkungen
• Erstellen Sie: lesbare display_name, short_description und default_prompt, indem Sie die Fertigkeit lesen
• Generieren Sie deterministisch, indem Sie die Werte als --interface key=value an scripts/generate_openai_yaml.py oder scripts/init_skill.py übergeben
• Bei Aktualisierungen: Validieren Sie, dass agents/openai.yaml noch mit SKILL.md übereinstimmt; regenerieren Sie, wenn veraltet
• Fügen Sie nur andere optionale Schnittstellenfelder (Symbole, Markenfarbe) hinzu, wenn sie explizit angegeben wurden
• Siehe references/openai_yaml.md für Felddefinitionen und Beispiele

Gebündelte Ressourcen (optional)

Skripte (scripts/)

Ausführbarer Code (Python/Bash/etc.) für Aufgaben, die deterministische Zuverlässigkeit erfordern oder wiederholt neu geschrieben werden.

• Wann einbinden: Wenn derselbe Code wiederholt neu geschrieben wird oder deterministische Zuverlässigkeit benötigt wird
• Beispiel: scripts/rotate_pdf.py für PDF-Drehaufgaben
• Vorteile: Tokeneffizient, deterministisch, können ohne Laden in den Kontext ausgeführt werden
• Hinweis: Skripte müssen möglicherweise dennoch von Codex gelesen werden, um Patches oder umgebungsspezifische Anpassungen vorzunehmen

Referenzen (references/)

Dokumentation und Referenzmaterial, das nach Bedarf in den Kontext geladen werden soll, um Codex' Prozess und Denken zu informieren.

• Wann einbinden: Für Dokumentation, auf die Codex während der Arbeit verweisen soll
• Beispiele: references/finance.md für Finanzschemata, references/mnda.md für die unternehmenseigene NDA-Vorlage, references/policies.md für Unternehmensrichtlinien, references/api_docs.md für API-Spezifikationen
• Anwendungsfälle: Datenbankschemata, API-Dokumentation, Domänenwissen, Unternehmensrichtlinien, detaillierte Workflow-Anleitungen
• Vorteile: Hält SKILL.md schlank, wird nur geladen, wenn Codex es für nötig hält
• Bewährte Vorgehensweise: Wenn Dateien groß sind (>10k Wörter), fügen Sie grep-Suchmuster in SKILL.md ein
• Duplikate vermeiden: Informationen sollten entweder in SKILL.md oder in Referenzdateien leben, nicht in beiden. Bevorzugen Sie Referenzdateien für detaillierte Informationen, es sei denn, sie sind wirklich zentral für die Fertigkeit – dies hält SKILL.md schlank, während Informationen auffindbar bleiben, ohne den Kontextfenster zu belasten. Behalten Sie nur wesentliche Verfahrensanweisungen und Workflow-Anleitungen in SKILL.md; verschieben Sie detailliertes Referenzmaterial, Schemata und Beispiele in Referenzdateien.

Assets (assets/)

Dateien, die nicht in den Kontext geladen, sondern in der von Codex produzierten Ausgabe verwendet werden sollen.

• Wann einbinden: Wenn die Fertigkeit Dateien benötigt, die in der endgültigen Ausgabe verwendet werden
• Beispiele: assets/logo.png für Marken-Assets, assets/slides.pptx für PowerPoint-Vorlagen, assets/frontend-template/ für HTML/React-Boilerplate, assets/font.ttf für Typografie
• Anwendungsfälle: Vorlagen, Bilder, Symbole, Boilerplate-Code, Schriftarten, Beispieldokumente, die kopiert oder geändert werden
• Vorteile: Trennt Ausgaberessourcen von der Dokumentation, ermöglicht Codex die Verwendung von Dateien, ohne sie in den Kontext zu laden

Was nicht in eine Fertigkeit aufgenommen werden sollte

Eine Fertigkeit sollte nur wesentliche Dateien enthalten, die ihre Funktionalität direkt unterstützen. Erstellen Sie KEINE überflüssigen Dokumentationen oder Hilfsdateien, einschließlich:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• usw.

Die Fertigkeit sollte nur die Informationen enthalten, die ein KI-Agent benötigt, um die anstehende Aufgabe zu erledigen. Sie sollte keine zusätzlichen Kontextinformationen über den Prozess enthalten, der zu ihrer Erstellung geführt hat, Einrichtungs- und Testverfahren, benutzerorientierte Dokumentation usw. Das Erstellen zusätzlicher Dokumentationsdateien führt nur zu Unordnung und Verwirrung.

Progressive-Offenlegung-Designprinzip

Fertigkeiten verwenden ein dreistufiges Ladesystem, um den Kontext effizient zu verwalten:

1. Metadaten (Name + Beschreibung) – Immer im Kontext (~100 Wörter)
2. SKILL.md-Text – Wenn die Fertigkeit ausgelöst wird (<5k Wörter)
3. Gebündelte Ressourcen – Nach Bedarf von Codex (unbegrenzt, da Skripte ausgeführt werden können, ohne in den Kontextfenster gelesen zu werden)

Progressive-Offenlegungsmuster

Halten Sie den SKILL.md-Text auf das Wesentliche und unter 500 Zeilen, um die Kontextaufblähung zu minimieren. Teilen Sie den Inhalt auf separate Dateien auf, wenn Sie sich dieser Grenze nähern. Wenn Sie Inhalte in andere Dateien auslagern, ist es sehr wichtig, diese von SKILL.md aus zu referenzieren und klar zu beschreiben, wann sie gelesen werden sollen, um sicherzustellen, dass der Leser der Fertigkeit von ihrer Existenz weiß und wann er sie verwenden soll.

Kernprinzip: Wenn eine Fertigkeit mehrere Variationen, Frameworks oder Optionen unterstützt, behalten Sie nur den Kern-Workflow und die Auswahlanleitung in SKILL.md. Verschieben Sie variationsspezifische Details (Muster, Beispiele, Konfiguration) in separate Referenzdateien.

Muster 1: High-Level-Anleitung mit Referenzen

# PDF-Verarbeitung

## Kurzanleitung

Text mit pdfplumber extrahieren:
[Codebeispiel]

## Erweiterte Funktionen

- **Formularausfüllung**: Siehe [FORMS.md](https://raw.githubusercontent.com/openai/codex/main/FORMS.md) für die vollständige Anleitung
- **API-Referenz**: Siehe [REFERENCE.md](https://raw.githubusercontent.com/openai/codex/main/REFERENCE.md) für alle Methoden
- **Beispiele**: Siehe [EXAMPLES.md](https://raw.githubusercontent.com/openai/codex/main/EXAMPLES.md) für gängige Muster

Codex lädt FORMS.md, REFERENCE.md oder EXAMPLES.md nur bei Bedarf.

Muster 2: Domänenspezifische Organisation

Organisieren Sie bei Fertigkeiten mit mehreren Domänen den Inhalt nach Domäne, um das Laden irrelevanter Kontexte zu vermeiden:

bigquery-skill/
├── SKILL.md (Übersicht und Navigation)
└── reference/
    ├── finance.md (Umsatz, Abrechnungsmetriken)
    ├── sales.md (Chancen, Pipeline)
    ├── product.md (API-Nutzung, Funktionen)
    └── marketing.md (Kampagnen, Attribution)

Wenn ein Benutzer nach Verkaufsmetriken fragt, liest Codex nur sales.md.

Analog dazu organisieren Sie bei Fertigkeiten, die mehrere Frameworks oder Varianten unterstützen, nach Variante:

cloud-deploy/
├── SKILL.md (Workflow + Providerauswahl)
└── references/
    ├── aws.md (AWS-Deployment-Muster)
    ├── gcp.md (GCP-Deployment-Muster)
    └── azure.md (Azure-Deployment-Muster)

Wenn der Benutzer AWS auswählt, liest Codex nur aws.md.

Muster 3: Bedingte Details

Zeigen Sie grundlegende Inhalte an, verlinken Sie zu erweiterten Inhalten:

# DOCX-Verarbeitung

## Dokumente erstellen

Verwenden Sie docx-js für neue Dokumente. Siehe [DOCX-JS.md](https://raw.githubusercontent.com/openai/codex/main/DOCX-JS.md).

## Dokumente bearbeiten

Für einfache Bearbeitungen ändern Sie das XML direkt.

**Für Nachverfolgung von Änderungen**: Siehe [REDLINING.md](https://raw.githubusercontent.com/openai/codex/main/REDLINING.md)
**Für OOXML-Details**: Siehe [OOXML.md](https://raw.githubusercontent.com/openai/codex/main/OOXML.md)

Codex liest REDLINING.md oder OOXML.md nur, wenn der Benutzer diese Funktionen benötigt.

Wichtige Richtlinien:

• Vermeiden Sie tief verschachtelte Referenzen – Halten Sie Referenzen eine Ebene tief von SKILL.md. Alle Referenzdateien sollten direkt von SKILL.md aus verlinken.
• Strukturieren Sie längere Referenzdateien – Fügen Sie bei Dateien mit mehr als 100 Zeilen oben ein Inhaltsverzeichnis ein, damit Codex den gesamten Umfang bei der Vorschau sehen kann.

Fertigkeitserstellungsprozess

Die Erstellung einer Fertigkeit umfasst folgende Schritte:

1. Die Fertigkeit anhand konkreter Beispiele verstehen
2. Wiederverwendbare Fertigkeitsinhalte planen (Skripte, Referenzen, Assets)
3. Die Fertigkeit initialisieren (init_skill.py ausführen)
4. Die Fertigkeit bearbeiten (Ressourcen implementieren und SKILL.md schreiben)
5. Die Fertigkeit validieren (quick_validate.py ausführen)
6. Basierend auf tatsächlicher Nutzung iterieren und komplexe Fertigkeiten vorwärtstesten.

Befolgen Sie diese Schritte der Reihe nach und überspringen Sie einen Schritt nur, wenn es einen klaren Grund gibt, warum er nicht anwendbar ist.

Benennung von Fertigkeiten

• Verwenden Sie nur Kleinbuchstaben, Ziffern und Bindestriche; normalisieren Sie vom Benutzer bereitgestellte Titel in Bindestrich-Schreibweise (z. B. "Plan Mode" -> plan-mode).
• Generieren Sie bei der Namensgenerierung einen Namen unter 64 Zeichen (Buchstaben, Ziffern, Bindestriche).
• Bevorzugen Sie kurze, verbgeführte Phrasen, die die Aktion beschreiben.
• Versehen Sie den Namensraum mit dem Tool, wenn dies die Klarheit oder Auslösung verbessert (z. B. gh-address-comments, linear-address-issue).
• Benennen Sie den Fertigkeitsordner genau nach dem Fertigkeitsnamen.

Schritt 1: Die Fertigkeit anhand konkreter Beispiele verstehen

Überspringen Sie diesen Schritt nur, wenn die Nutzungsmuster der Fertigkeit bereits klar verstanden sind. Er bleibt wertvoll, selbst wenn Sie mit einer vorhandenen Fertigkeit arbeiten.

Um eine effektive Fertigkeit zu erstellen, verstehen Sie klar konkrete Beispiele dafür, wie die Fertigkeit verwendet wird. Dieses Verständnis kann entweder aus direkten Benutzerbeispielen oder generierten Beispielen stammen, die mit Benutzerfeedback validiert wurden.

Beispiel: Beim Erstellen einer Fertigkeit zur Bildbearbeitung umfassen relevante Fragen:

• "Welche Funktionalität sollte die Fertigkeit zur Bildbearbeitung unterstützen? Bearbeiten, Drehen, noch etwas anderes?"
• "Können Sie einige Beispiele nennen, wie diese Fertigkeit verwendet würde?"
• "Ich kann mir vorstellen, dass Benutzer Dinge wie 'Entferne den Rote-Augen-Effekt aus diesem Bild' oder 'Drehe dieses Bild' fragen. Gibt es andere Arten, wie Sie sich vorstellen, dass diese Fertigkeit verwendet wird?"
• "Was würde ein Benutzer sagen, das diese Fertigkeit auslösen sollte?"
• "Wo soll ich diese Fertigkeit erstellen? Wenn Sie keine Präferenz haben, platziere ich sie in $CODEX_HOME/skills (oder ~/.codex/skills, wenn CODEX_HOME nicht gesetzt ist), damit Codex sie automatisch erkennen kann."

Um Benutzer nicht zu überfordern, vermeiden Sie es, zu viele Fragen in einer einzigen Nachricht zu stellen. Beginnen Sie mit den wichtigsten Fragen und fragen Sie bei Bedarf nach, um eine bessere Effektivität zu erzielen.

Schließen Sie diesen Schritt ab, wenn Sie ein klares Gefühl dafür haben, welche Funktionalität die Fertigkeit unterstützen soll.

Schritt 2: Planung der wiederverwendbaren Fertigkeitsinhalte

Um konkrete Beispiele in eine effektive Fertigkeit umzuwandeln, analysieren Sie jedes Beispiel, indem Sie:

1. Überlegen, wie das Beispiel von Grund auf ausgeführt werden könnte
2. Identifizieren, welche Skripte, Referenzen und Assets bei der wiederholten Ausführung dieser Workflows hilfreich wären

Beispiel: Beim Erstellen einer pdf-editor-Fertigkeit zur Verarbeitung von Anfragen wie "Hilf mir, dieses PDF zu drehen", zeigt die Analyse:

1. Das Drehen eines PDF erfordert jedes Mal das Neuschreiben desselben Codes
2. Ein Skript scripts/rotate_pdf.py wäre hilfreich, um es in der Fertigkeit zu speichern

Beispiel: Beim Entwerfen einer frontend-webapp-builder-Fertigkeit für Anfragen wie "Erstelle mir eine Todo-App" oder "Erstelle mir ein Dashboard zum Verfolgen..."

[truncated for translation]