aiskillstore/marketplace

Skill-Ersteller

Erstellen Sie Skills, die Codex nützliche, nicht offensichtliche Anleitungen geben, ohne die Arbeit an unzusammenhängenden Themen einzuschränken.

Kernprinzipien

Gehen Sie davon aus, dass Codex bereits fähig ist. Fügen Sie nur Informationen ein, die seine Entscheidungen ändern oder seine Arbeit verbessern. Entfernen Sie generische Ratschläge, wiederholte Anweisungen, spekulative Randfälle und Beispiele, die die Aufgabe nicht wesentlich klären.

Bewahren Sie die Benutzerabsicht und den Umfang. Ein Skill sollte die angeforderte Aufgabe unterstützen, nicht das vom Benutzer gewählte Produkt ersetzen, den Auftrag erweitern, unzusammenhängende Konfigurationen ändern oder die Berechtigung für zusätzliche externe Aktionen implizieren. Machen Sie ein bestimmtes Beispiel, einen früheren Fehler oder eine persönliche Präferenz nicht zu einer universellen Anforderung.

Die Genehmigung zur Durchführung einer Aufgabe erweitert nicht ihren Umfang oder ihre Ausführungsberechtigungen. Für Wiederholungs- oder extern mutierende Arbeitsabläufe definieren Sie eine Stoppbedingung, die dem Risiko angemessen ist.

Passen Sie die Spezifität an das Risiko an. Geben Sie dem Modell Raum, einen geeigneten Ansatz zu wählen, wenn mehrere Ansätze vernünftig sind. Verwenden Sie detaillierte Schritte, deterministische Skripte oder absolute Sprache nur, wenn Korrektheit, Sicherheit, Berechtigungen oder ein wirklich fragiler Arbeitsablauf dies erfordern.

Beschreiben Sie für offene Arbeiten das Ergebnis und die relevanten Entscheidungskriterien. Bieten Sie für Arbeitsabläufe mit einer bevorzugten Form nützliche Beispiele oder konfigurierbare Skripte. Reservieren Sie feste Sequenzen und enge Parameter für Vorgänge, bei denen eine Abweichung ein konkretes Problem verursachen würde. Bewahren Sie nicht offensichtliche betriebliche Invarianten, unterscheiden Sie tatsächliche Anforderungen von optionalen Empfehlungen oder lokalen Konventionen und vermeiden Sie die Wiederholung von Richtlinien, die bereits an anderer Stelle durchgesetzt werden.

Halten Sie die Erkennung kostengünstig und präzise. Skill-Namen und -Beschreibungen sind verfügbar, bevor ein Skill geladen wird. Beschreiben Sie die tatsächliche Fähigkeit und wann sie angewendet wird, und fügen Sie Ausschlüsse nur hinzu, wenn sie wahrscheinliche Fehlleitungen verhindern. Vermeiden Sie erschöpfende Fähigkeitslisten und Sammelbegriffe, die unzusammenhängende Anfragen anziehen.

Halten Sie Skills in sich geschlossen; verweisen Sie nur auf einen anderen Skill oder ein anderes Tool, wenn der angeforderte Arbeitsablauf dies wirklich erfordert und es in der Zielumgebung verfügbar ist. Spezialisierte Überprüfungs-, Härtungs- oder Audit-Workflows sollten nur angewendet werden, wenn sie angefordert oder wirklich benötigt werden, nicht nur, weil gewöhnliche Arbeit das gleiche Thema berührt.

Offenlegung von Details schrittweise. Halten Sie gemeinsame Zwecke, wesentliche Einschränkungen und nützliche Routen in SKILL.md. Platzieren Sie umfangreiche modusspezifische Anleitungen, Schemata, Beispiele oder Prozeduren in unterstützenden Referenzen und lesen Sie nur die für die aktuelle Aufgabe relevanten Referenzen. Ein einfacher, in sich geschlossener Skill benötigt keinen Router oder zusätzliche Dateien.

Anatomie eines Skills

Jeder Skill ist ein Ordner, der eine erforderliche SKILL.md-Datei und alle optionalen Ressourcen enthält, die sein tatsächlicher Workflow benötigt:

skill-name/
|-- SKILL.md                 Erforderliche Skill-Anweisungen
|   |-- YAML-Frontmatter     Erforderlicher Name und Beschreibung
|   `-- Markdown-Text        Anweisungen, die geladen werden, wenn der Skill verwendet wird
|-- agents/                  Optionale UI-Metadaten und Aufrufrichtlinie
|   `-- openai.yaml
|-- scripts/                 Optionale ausführbare Helfer
|-- references/              Optionale Dokumentation, die nach Bedarf geladen wird
`-- assets/                  Optionale Dateien, die in der generierten Ausgabe verwendet werden

Wählen Sie die Struktur, die zur tatsächlichen Aufgabe passt. Manche Skills sind kurz und in sich geschlossen; andere routen zwischen Betriebsmodi oder delegieren komplexe Mechaniken an Skripte. Vermeiden Sie die Erstellung von Verzeichnissen, Platzhaltern, Beispielen oder ergänzender Dokumentation ohne klaren Verwendungszweck.

SKILL.md

Das YAML-Frontmatter identifiziert den Skill und bestimmt, wann er berücksichtigt werden soll. Fügen Sie den erforderlichen name und description ein und bewahren Sie vorhandene optionale Felder wie bestehendes metadata auf, wenn angemessen.

Der Markdown-Text wird nur geladen, wenn der Skill verwendet wird. Platzieren Sie den Zweck, den wesentlichen Workflow, die tatsächlichen Einschränkungen und nützliche Links dort. Halten Sie detaillierte Prozeduren und Beispiele in unterstützenden Referenzen, wenn sie nur für bestimmte Modi relevant sind.

Skill-Informationen werden in drei Stufen offengelegt:

1. Name und Beschreibung: Während der Skill-Auswahl verfügbar, daher halten Sie sie prägnant und unterscheidend.
2. SKILL.md-Text: Wird geladen, wenn der Skill angewendet wird, daher halten Sie die Anweisungen für diese Aufgabe relevant.
3. Unterstützende Ressourcen: Werden nur gelesen oder ausgeführt, wenn die aktuelle Aufgabe sie tatsächlich benötigt.

Der Einstiegspunkt sollte so kurz sein, wie es die Aufgabe erlaubt, während wichtige Einschränkungen erhalten bleiben. Eine große Obergrenze ist kein Ziel: Verschieben Sie bedingte Details in Referenzen, wenn dies die Klarheit oder die Nutzung des Kontexts verbessert, anstatt zu warten, bis die Datei unhandlich wird.

Skripte

Verwenden Sie scripts/ für ausführbaren Code, wenn dieselbe Logik sonst wiederholt neu geschrieben werden müsste oder eine deterministische Ausführung die Zuverlässigkeit wesentlich verbessert.

• Beispiel: scripts/rotate_pdf.py für eine PDF-Operation, die sonst das erneute Erstellen desselben Codes erfordern würde.
• Nützlich für: Wiederholte Transformationen, zuverlässige API-Operationen, Datenverarbeitung und andere konkrete Automatisierungen.
• Validierung: Führen Sie neue oder geänderte Skripte aus, um ihr Verhalten zu überprüfen. Skripte können normalerweise ausgeführt werden, ohne ihre vollständige Implementierung in den Kontext zu laden, obwohl ein Agent sie möglicherweise inspizieren muss, wenn er sie patcht oder anpasst.

Referenzen

Verwenden Sie references/ für Dokumentation, die nur in bestimmten Kontexten benötigt wird.

• Beispiele: references/schema.md für Datenbanktabellen, references/policies.md für Domänenregeln, references/api_docs.md für eine API oder separate Schreibanleitungen für verschiedene Liefergegenstände.
• Nützlich für: Schemata, API-Dokumentation, Unternehmensrichtlinien, formatspezifische Prozeduren, detaillierte Workflows und umfangreiche Beispiele.
• Routing: Verlinken Sie jede Referenz von SKILL.md oder einer anderen relevanten Ressource aus und erklären Sie, wann sie gelesen werden sollte. Halten Sie Informationen an einem Ort, anstatt sie über den Einstiegspunkt und die Referenzen zu duplizieren.

Halten Sie Referenzen fokussiert auf gepflegte, aufgabenspezifische Informationen, die die Entscheidungen des Agenten ändern. Vermeiden Sie kopierte Handbücher, erschöpfende Kataloge und generische Tutorials, die bereits von autoritativen Quellen verfügbar sind. Bevor Sie vorhandene Ressourcen entfernen, überprüfen Sie deren Aufrufer und Zweck.

Fügen Sie für große Referenzen nützliche Suchbegriffe oder einen kurzen Inhaltsabschnitt ein, wenn dies das Auffinden des benötigten Materials erleichtert.

Assets

Verwenden Sie assets/ für Dateien, die zur generierten Ausgabe gehören, nicht zu den Anweisungen des Modells.

• Beispiele: assets/logo.png, assets/slides.pptx, assets/font.ttf oder assets/frontend-template/.
• Nützlich für: Vorlagen, Bilder, Schriftarten, Symbole, Boilerplate-Projekte und andere Dateien, die in das Ergebnis kopiert oder angepasst werden.
• Kontext: Laden Sie Assets nicht als Anweisungen, es sei denn, die Aufgabe erfordert deren Überprüfung.

UI-Metadaten und Aufrufrichtlinie

agents/openai.yaml kann UI-bezogene Metadaten wie display_name, short_description und default_prompt sowie die Aufrufrichtlinie bereitstellen. Lesen Sie beim Erstellen oder Aktualisieren dieser Einstellungen references/openai_yaml.md und halten Sie die Werte konsistent mit dem Skill.

Die automatische Skill-Auswahl ist standardmäßig erlaubt. Ändern Sie diese Voreinstellung nur, wenn der Benutzer explizit einen Nur-explizit-Skill anfordert:

policy:
  allow_implicit_invocation: false

Dies hält den Skill bei explizitem Aufruf als $skill-name verfügbar, ohne ihn automatisch zum Modellkontext hinzuzufügen. Bewahren Sie bei der Aktualisierung von agents/openai.yaml nicht zusammenhängende vorhandene UI-, Richtlinien- und Abhängigkeitsfelder auf.

Der Initialisierer erstellt diese Datei automatisch. Für neue oder nur Schnittstellen-Metadaten generieren Sie sie mit:

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

Der Generator ersetzt die gesamte Datei. Wenn eine vorhandene Datei policy oder dependencies enthält, aktualisieren Sie nur die beabsichtigten Felder direkt, anstatt sie neu zu generieren.

Fügen Sie optionale Schnittstellenfelder nur ein, wenn der Benutzer sie bereitstellt oder anfordert.

Was nicht enthalten sein sollte

Fügen Sie Dateien ein, die die Arbeit des Skills direkt unterstützen. Vermeiden Sie das Hinzufügen einer README.md, Installationsanleitung, Änderungsprotokolls, duplizierten Kurzreferenz oder anderen ergänzenden Dokumentation, es sei denn, eine bestimmte Aufgabe oder ein Verpackungsanforderung erfordert dies.

Progressive Offenlegung in der Praxis

Für einen Skill mit mehreren umfangreichen Modi halten Sie die gemeinsamen Anleitungen und Modusauswahlkriterien in SKILL.md. Verlinken Sie jede unterstützende Referenz dort, wo ihre Verwendung relevant wird. Laden Sie nicht jede Referenz standardmäßig, duplizieren Sie Referenzinhalte im Einstiegspunkt oder fügen Sie eine Routing-Schicht hinzu, wenn es nichts Sinnvolles zu routen gibt.

Beispielsweise kann ein Bereitstellungsskill die Providerauswahl in SKILL.md und separate Providerdetails belassen:

cloud-deploy/
|-- SKILL.md
`-- references/
    |-- aws.md
    |-- gcp.md
    `-- azure.md

Wenn der Benutzer AWS wählt, lesen Sie references/aws.md; laden Sie nicht auch die GCP- und Azure-Anleitungen. Das gleiche Muster kann Geschäftsdomänen, Liefergegenstandsarten oder andere wirklich unterschiedliche Betriebsmodi trennen.

Ein kurzer Skill kann stattdessen nur dann zu Details routen, wenn ein fortgeschrittener Vorgang sie benötigt:

## Dokumente

Behandeln Sie gewöhnliche Bearbeitungen direkt.

- Für Änderungsverfolgung lesen Sie [references/redlining.md](references/redlining.md).
- Für Dokumenteninterna lesen Sie [references/ooxml.md](references/ooxml.md).

Diese Beispiele veranschaulichen Optionen, keine erforderliche Struktur. Wählen Sie die Organisation, die die Verwendung des Skills erleichtert, ohne irrelevantes Material zu laden.

Erstellen oder Aktualisieren eines Skills

Passen Sie die Arbeit an die Anfrage an. Das Erstellen eines komplexen neuen Skills kann das Verständnis realistischer Anwendungsfälle, die Auswahl unterstützender Ressourcen, das Initialisieren von Dateien, das Schreiben von Anweisungen und das Validieren des Ergebnisses umfassen. Eine enge Aktualisierung eines vorhandenen Skills erfordert möglicherweise nur eine fokussierte Bearbeitung und Validierung.

Stellen Sie klärende Fragen nur, wenn die fehlenden Informationen wichtig sind und nicht sinnvoll abgeleitet werden können. Respektieren Sie einen vom Benutzer angegebenen Speicherort; erstellen Sie andernfalls auffindbare Skills in $CODEX_HOME/skills oder ~/.codex/skills, wenn CODEX_HOME nicht gesetzt ist.

Halten Sie die automatische Skill-Auswahl aktiviert, es sei denn, der Benutzer fordert explizit einen Nur-explizit-Skill an. Wenn der beabsichtigte Aufrufmodus wirklich unklar ist und für den angeforderten Workflow wichtig ist, fragen Sie, ob der Benutzer die normale automatische Erkennung oder einen Nur-explizit-Aufruf wünscht; andernfalls behalten Sie die Voreinstellung bei. Leiten Sie den Nur-explizit-Aufruf nicht aus sensiblen Vorgängen oder erforderlichen Genehmigungen ab: Halten Sie den Skill auffindbar und fordern Sie die Autorisierung unmittelbar vor der tatsächlichen Mutation an. Bewahren Sie die Aufrufrichtlinie eines vorhandenen Skills, es sei denn, der Benutzer bittet um eine Änderung.

Berücksichtigen Sie für einen neuen oder wesentlich überarbeiteten Skill die tatsächlichen Anfragen, die er bearbeiten soll, und welche wiederverwendbaren Ressourcen diese Aufgaben verbessern würden:

• Eine wiederholte PDF-Transformation kann einen Hilfshelfer wie scripts/rotate_pdf.py rechtfertigen.
• Ein Workflow zur Erstellung von Anwendungen kann von einem Starter wie assets/frontend-template/ profitieren.
• Ein Skill zur Datenanalyse benötigt möglicherweise eine Anleitung wie references/schema.md, um das erneute Entdecken von Tabellenbeziehungen zu vermeiden.

Erstellen Sie diese Ressourcen nur, wenn ihr konkreter Nutzen dies rechtfertigt. Wenn der Benutzer die Aufgabe bereits klar erklärt hat, fahren Sie fort, ohne zusätzliche Beispiele anzufordern.

Namensgebung

• Verwenden Sie Kleinbuchstaben, Ziffern und Bindestriche.
• Halten Sie Namen unter 64 Zeichen und bevorzugen Sie kurze, handlungsorientierte Namen.
• Versehen Sie den Namespace mit dem Tool oder der Domäne, wenn dies die Auffindbarkeit verbessert.
• Benennen Sie den Skill-Ordner nach dem Skill.

Initialisieren eines neuen Skills

Verwenden Sie für einen neuen Skill den gebündelten Initialisierer, wenn er hilft, die erforderlichen Dateien konsistent zu erstellen:

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

Zum Beispiel:

scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references

Fordern Sie nur die Ressourcenverzeichnisse an, die der Skill benötigt. Verwenden Sie --examples nur, wenn konkrete Platzhalter helfen würden, und ersetzen oder entfernen Sie sie vor Abschluss. Initialisieren Sie einen vorhandenen Skill nicht erneut.

Der Initialisierer erstellt das Skill-Verzeichnis, einen prägnanten SKILL.md-Starter und agents/openai.yaml. Er erstellt Ressourcenverzeichnisse und Beispieldateien nur auf Anfrage. Übergeben Sie generierte UI-Werte als --interface key=value, wenn nötig.

Schreiben der Anweisungen

Die description im Frontmatter sollte kurz erklären, was der Skill tut und wann er angewendet wird. Fügen Sie eine sinnvolle Abgrenzung ein, wenn ähnliche Anfragen den Skill nicht aktivieren sollen.

Zum Beispiel:

description: Erstellen oder Bearbeiten von Word-Dokumenten, wenn Formatierung, Änderungsverfolgung oder Kommentare eine dokumentspezifische Handhabung erfordern.

Platzieren Sie detaillierte Workflows, Tool-Auswahlen, Beispiele und Betriebsmodi im Textkörper oder in relevanten Referenzen, anstatt sie alle in der Beschreibung aufzulisten. Bewahren Sie unterstützte optionale Frontmatter-Felder wie vorhandenes metadata auf, wenn angemessen.

Schreiben Sie nur die Anweisungen, die für eine andere Codex-Instanz erforderlich sind, um die Aufgabe gut auszuführen. Geben Sie das gewünschte Ergebnis, den nicht offensichtlichen Kontext, die tatsächlichen Einschränkungen und relevante Referenzen oder Tools an. Bewahren Sie die expliziten Entscheidungen des Benutzers und vorhandene Autorisierungsgrenzen. Vermeiden Sie die Vorgabe einer festen Struktur, eines Prozesses oder einer Anzahl von Schritten, wenn die Aufgabe dies nicht erfordert.

Validieren und Iterieren

Validieren Sie den fertigen Skill mit:

scripts/quick_validate.py <path/to/skill-folder>

Der Validator prüft Frontmatter, Namensgebung und unvollständige Gerüstplatzhalter; er beweist nicht, dass der Skill gute Entscheidungen trifft. Überprüfen Sie auch, dass Beschreibungen unterscheidend bleiben, Anweisungen die Benutzerabsicht bewahren, Referenzen auffindbar sind und alle hinzugefügten Skripte tatsächlich funktionieren.

Wenn Tests gerechtfertigt sind, überprüfen Sie beobachtbares Verhalten oder sinnvolle Invarianten. Vermeiden Sie Tests, die lediglich generierte Formulierungen, Überschriften oder Regex-Muster abgleichen.

Verbessern Sie den Skill basierend auf tatsächlicher Nutzung oder gezeigten Fehlern. Bevorzugen Sie eine enge Korrektur gegenüber der Akkumulation universeller Regeln für jedes hypothetische Szenario.