Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design
Mar 9, 2026 Codex

Open-Source-Projekte mit Skills schneller pflegen

Wie wir mit Skills und GitHub Actions die Codex-Workflows in den Repositorys des OpenAI Agents SDK verbessern.

Verfasst von: Kazuhiro Sera

Open-Source-Projekte mit Skills schneller pflegen

Mit Codex ändern wir die Art, wie wir die Repositorys des OpenAI Agents SDK pflegen. Mit Skills im Repository, AGENTS.md und GitHub Actions machen wir aus wiederkehrenden Entwicklungsaufgaben wiederholbare Workflows. Dazu gehören das Prüfen von Änderungen, die Release-Vorbereitung, Integrationstests für Beispiele und die Prüfung von Pull Requests. Schon mit einem recht einfachen Setup konnten wir den Durchsatz bei der Entwicklung in diesen aktiven Repositorys steigern. Vom 1. Dezember 2025 bis zum 28. Februar 2026 haben wir in beiden Repositorys insgesamt 457 Pull Requests zusammengeführt. In den drei Monaten davor, vom 1. September bis zum 30. November 2025, waren es 316. Bei Python stieg die Zahl von 182 auf 226, bei TypeScript von 134 auf 231.

Zur Einordnung: Das SDK gibt es für Python und TypeScript. Es liefert die zentralen Bausteine für Anwendungen mit Agenten. Auf Basis der Realtime API lassen sich damit auch mit wenig Code Sprachagenten entwickeln, die mehrere Agenten und Tools einbinden und bei Bedarf Menschen in Entscheidungen einbeziehen. Das SDK ist weit verbreitet. In den zuletzt erfassten 30-Tage-Zeiträumen (Stand: 6. März 2026) verzeichnete das Python-Paket auf PyPI rund 14,7 Millionen Downloads, das TypeScript-Paket auf npm rund 1,5 Millionen.

Unser Setup besteht aus wenigen Teilen:

  • Regeln für das Repository in AGENTS.md
  • Skills im Repository unter .agents/skills/
  • optionale Skripte und Referenzmaterial in diesen Skills
  • die Codex GitHub Action, wenn derselbe Workflow in der CI laufen soll

So hat Codex verlässlichen Kontext dazu, wie wir im jeweiligen Repository arbeiten, und kann wiederkehrende Entwicklungsaufgaben schneller und genauer erledigen.

Wenn du ein öffentliches Open-Source-Projekt pflegst, schau dir Codex for OSS an. Wenn du die Voraussetzungen erfüllst, kannst du ChatGPT Pro mit Codex, API-Credits und unter bestimmten Bedingungen Zugang zu Codex Security beantragen.

Workflows im Repository festhalten

In diesen Repositorys halten wir die jeweiligen Arbeitsabläufe in Skills fest. Ein Skill bündelt das Wissen, das für einen bestimmten Ablauf nötig ist. Er besteht aus einem SKILL.md-Manifest und optional den Verzeichnissen scripts/, references/ und assets/. Die Dokumentation zur Anpassung von Codex erklärt, warum sich Skills für wiederholbare Workflows eignen. Sie können ausführliche Anweisungen, Skripte und Referenzmaterial enthalten, ohne den Kontext des Agenten schon zu Beginn unnötig zu vergrößern.

Codex lädt die Informationen zu einem Skill schrittweise:

  • Zuerst sieht Codex Metadaten wie name und description.
  • Codex lädt SKILL.md erst, wenn es den Skill auswählt.
  • Es liest Referenzmaterial oder führt Skripte nur bei Bedarf aus.

In beiden SDK-Repositorys liegen die Workflows direkt beim Code:

Das Python-Repository zeigt das Grundmuster:

  • code-change-verification führt die vorgeschriebenen Schritte für Formatierung, Linting, Typprüfung und Tests aus, wenn sich der Code oder das Build-Verhalten ändert.
  • docs-sync gleicht die Dokumentation mit dem Code ab und findet fehlende, fehlerhafte oder veraltete Inhalte.
  • examples-auto-run führt Beispiele im automatischen Modus aus, protokolliert die Ergebnisse und erleichtert es, einzelne Läufe zu wiederholen.
  • final-release-review vergleicht den Tag des vorherigen Releases mit dem aktuellen Release-Kandidaten und prüft, ob dieser bereit für die Veröffentlichung ist.
  • implementation-strategy klärt vor Änderungen an der Laufzeit oder der API, wo Kompatibilität gewahrt bleiben muss und wie die Änderung umgesetzt werden soll.
  • openai-knowledge ruft über den offiziellen Docs-MCP-Workflow die aktuelle Dokumentation zur OpenAI API und zur Plattform ab.
  • pr-draft-summary schlägt bei der Übergabe einen Branch-Namen vor und erstellt einen PR-Titel sowie einen Entwurf für die Beschreibung.
  • test-coverage-improver misst die Testabdeckung, ermittelt die größten Lücken und schlägt Tests vor, die besonders wichtige Lücken schließen würden.

Das JavaScript-Repository folgt demselben Muster. Für das npm-Monorepo und den Release-Prozess kommen einige spezifische Skills hinzu:

  • changeset-validation prüft, ob die Changesets und die vorgesehenen Versionssprünge zu den tatsächlichen Paketänderungen passen.
  • integration-tests veröffentlicht Pakete in einer lokalen Verdaccio-Registry und prüft, ob sie sich in den unterstützten Laufzeitumgebungen installieren und ausführen lassen.
  • pnpm-upgrade aktualisiert die pnpm-Toolchain und die in der CI festgelegten Versionen gemeinsam.

Wichtiger als die genaue Liste ist das Muster. Jeder Skill hat eine eng umrissene Aufgabe, einen klaren Auslöser und ein konkretes Ergebnis.

Einige der nützlichsten Skills setzen keine zwingende Freigabebedingung. docs-sync und test-coverage-improver erstellen zunächst einen Bericht. Sie untersuchen den aktuellen Diff oder die Ergebnisse der Abdeckungsmessung, priorisieren ihre Befunde und holen vor Änderungen eine Genehmigung ein. Im Python-Repository verwendet docs-sync die Docstrings und Kommentare im Quellcode als maßgebliche Grundlage für die generierte Referenzdokumentation. Änderungen erfolgen dort, statt die generierte Ausgabe von Hand zu bearbeiten. Der nur im JavaScript-Repository verwendete Skill pnpm-upgrade zeigt ebenfalls, wie eng sich eine Wartungsaufgabe eingrenzen lässt. Er aktualisiert die lokale pnpm-Version, packageManager und die in den Workflows festgelegten Versionen gemeinsam, ohne im gesamten Repository pauschal Text zu suchen und zu ersetzen.

Workflows verbindlich machen

Skills sind nützlicher, wenn das Repository ihren Einsatz zum richtigen Zeitpunkt vorschreibt. Dafür nutzen wir AGENTS.md.

Laut dem Leitfaden zu AGENTS.md enthalten diese Dateien Anweisungen für das jeweilige Repository. Sie gehören zum Codebestand und gelten schon, bevor der Agent mit der Arbeit beginnt. Der Leitfaden empfiehlt außerdem, die Dateien kurz zu halten. In den Repositorys des Agents SDK halten wir dort die Regeln fest, die Codex jedes Mal befolgen soll. Die wichtigsten stehen weit oben.

In der Praxis legen beide Repositorys mit kurzen Wenn-dann-Regeln fest, wann ein Skill Pflicht ist. Rufe vor Änderungen an der Laufzeit oder der API $implementation-strategy auf, um zu klären, wo Kompatibilität gewahrt bleiben muss und wie du vorgehst. Betrifft eine Änderung SDK-Code, Tests, Beispiele oder das Build-Verhalten, rufe $code-change-verification auf. Wirkt sich eine Änderung an einem JavaScript-Paket auf die Release-Metadaten aus, rufe $changeset-validation auf. Betrifft die Arbeit Integrationen mit der OpenAI API oder der Plattform, rufe $openai-knowledge auf. Sobald die Arbeit abgeschlossen und bereit zur Übergabe ist, rufe $pr-draft-summary auf.

Dieser Aufbau entspricht auch den Empfehlungen von agents.md. Projektüberblick, Build- und Testbefehle, Codestil, Hinweise zum Testen, Sicherheitsaspekte und weitere Regeln für das Repository stehen an einer Stelle. Die Repositorys des Agents SDK folgen diesem Aufbau und stellen die Auslöser voran, die im Arbeitsalltag am wichtigsten sind. Eine kompakte Fassung sieht so aus:

# AGENTS.md

## Project overview

- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.

## Mandatory skill usage

- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.

## Build and test commands

- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`

## Compatibility rules

- Preserve positional compatibility for public constructors and dataclass fields.

Die tatsächlichen Dateien ergänzen dieses Grundgerüst um Details für das jeweilige Repository. Dazu gehören $changeset-validation im JavaScript-Repository sowie ausführlichere Vorgaben zu Laufzeit, Dokumentation und Releases in beiden Dateien. Die vollständigen Beispiele findest du in AGENTS.md in openai-agents-python und AGENTS.md in openai-agents-js.

AGENTS.md eignet sich auch für Regeln, die über den Aufruf von Skills hinausgehen. Das Python-Repository hält dort eine Kompatibilitätsregel für die öffentliche API fest. Die Position exportierter Konstruktorparameter und Dataclass-Felder muss ihre bisherige Bedeutung behalten. Neue optionale Parameter und Felder sollen nach Möglichkeit am Ende stehen. Lässt sich eine Umordnung nicht vermeiden, sind Kompatibilitätstests zu ergänzen. So stehen die für ein Release entscheidenden Kompatibilitätsregeln an derselben Stelle wie die Auslöser für Skills.

Regeln für die Überprüfung

Ein anschauliches Beispiel ist $code-change-verification.

Keines der beiden Repositorys verlangt, bei jeder Aufgabe eine lange Reihe von Prüfungen auszuführen. Die Regel lautet: „Führe die Prüfungen aus, wenn sich Laufzeitcode, Tests, Beispiele oder das Build- oder Testverhalten geändert haben. Schließe die Aufgabe erst ab, wenn alle Prüfungen bestanden sind.“

So bleibt der Aufwand bei reinen Dokumentationsänderungen gering. Bei Änderungen am SDK-Code sind die Standardprüfungen des Repositorys dagegen Pflicht.

Welche Schritte zur Überprüfung gehören, legen die Skills selbst fest.

Im Python-Repository schreibt der Skill diese Befehle vor:

make format
make lint
make typecheck
make tests

Im JavaScript-Repository schreibt der Skill genau diese Reihenfolge vor:

pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test

Der Skill legt fest, wann eine Änderung im Repository als „geprüft“ gilt. AGENTS.md macht diese Definition verbindlich.

Changesets validieren

Für Paketänderungen schreibt das JavaScript-Repository einen weiteren Schritt vor: $changeset-validation basiert auf Changesets.

Wenn sich etwas unter packages/ oder in .changeset/ ändert, muss das Modell mehr tun, als die Tests auszuführen. Es muss das passende Changeset erstellen oder aktualisieren, den vorgesehenen Versionssprung prüfen und bestätigen, dass das Changeset mit dem Diff übereinstimmt.

Der Skill prüft mehr als die bloße Existenz einer Datei. Codex soll den Git-Diff beurteilen. Die Prüfregeln stehen in einem gemeinsamen Prompt, sodass lokal und in GitHub Actions dieselbe Logik gilt. Der Skill enthält außerdem Regeln für dieses Repository:

  • Wenn der Branch bereits ein Changeset enthält, verwende es weiter, statt ein zweites anzulegen.
  • Beschränke die Zusammenfassung auf eine Zeile im Stil von Conventional Commits, damit sie zugleich als Commit-Titel dienen kann.
  • Vermeide vor Version 1.0 bei gewöhnlichen Funktionserweiterungen einen Sprung der Hauptversion. Behandle Ergänzungen, die ausdrücklich nur als Vorschau gekennzeichnet sind, als Patch-Änderungen, sofern sie das bisherige Verhalten beibehalten.
  • Prüfe anhand der tatsächlichen Paketänderungen, welcher Versionssprung erforderlich ist.

Codex muss die selbst erstellten Release-Metadaten also prüfen, bevor es die Arbeit als abgeschlossen melden kann.

Aktuelle Dokumentation verwenden

Beide Repositorys schreiben $openai-knowledge vor, wenn eine Aufgabe Integrationen mit der OpenAI API oder der Plattform betrifft.

Der Skill greift mit wenig eigener Logik auf den offiziellen OpenAI Docs MCP zu. Anstatt aus dem Gedächtnis zu antworten, soll Codex über den MCP-Server für die OpenAI-Entwicklungsdokumentation aktuelle Informationen etwa zur Responses API, zu Tools, Streaming, Realtime und MCP nachschlagen.

Ist der MCP-Server in der lokalen Codex-Umgebung noch nicht konfiguriert, verweist der Skill auf den Schnellstart für Docs MCP und den offiziellen Endpunkt des MCP-Servers.

Die Übergabe des Pull Requests vorbereiten

Zum Abschluss größerer Arbeiten nutzen beide Repositorys $pr-draft-summary.

Der Skill wird erst aktiv, wenn die Aufgabe praktisch abgeschlossen oder bereit zur Prüfung ist. Die Änderung muss wesentliche Teile des Codes, Tests, Beispiele, Dokumentation mit Auswirkungen auf das Verhalten oder die Build- oder Testkonfiguration betreffen. Der Skill erfasst dann automatisch den Branch-Namen, den Status des Arbeitsverzeichnisses, die geänderten Dateien, die Diff-Statistik und die letzten Commits. Daraus erstellt er:

  • einen Vorschlag für den Branch-Namen
  • einen PR-Titel
  • einen Entwurf für die PR-Beschreibung

Das Ausgabeformat ist bewusst fest vorgegeben. Ein typisches Ergebnis sieht so aus:

# Pull Request Draft

## Branch name suggestion

git checkout -b fix/tracing-lazy-init-fork-safety

## Title

fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards

## Description

This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.

It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.

It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.

This pull request resolves #2489.

Wenn du dem Modell zutraust, seine eigene Arbeit zu prüfen und zusammenzufassen, kannst du es zum Abschluss auch den PR-Entwurf erstellen lassen. So läuft die Übergabe einheitlich ab, und nach der eigentlichen Programmierarbeit fällt weniger wiederkehrende Schreibarbeit an.

Aussagekräftigere Beschreibungen schreiben

Das Feld description in den Frontmatter-Metadaten der SKILL.md eines Skills bestimmt mit, wie Codex einer Aufgabe den passenden Skill zuordnet.

Die Beschreibung hat also eine technische Funktion. Die Spezifikation für Agent Skills schreibt name und description als Frontmatter-Felder in SKILL.md vor. Sie legt außerdem fest, dass beim Start zunächst diese Felder für alle Skills geladen werden. Der vollständige Inhalt von SKILL.md sowie gegebenenfalls scripts/, references/ und assets/ werden erst geladen, wenn der Skill tatsächlich aktiviert wird.

Die Dokumentation zu Codex-Skills und die Dokumentation zur Anpassung von Codex beschreiben dasselbe Verhalten aus Sicht von Codex. Codex ermittelt anhand der Metadaten, welche Skills infrage kommen, lädt SKILL.md erst bei der Auswahl des Skills und liest Referenzmaterial oder führt Skripte nur bei Bedarf aus. Der Cookbook-Beitrag zu Skills in der OpenAI API beschreibt den Ablauf für die Hosted Shell ebenso genau. OpenAI liest zunächst name, description und den Pfad jedes Skills. Anhand dieser Informationen entscheidet das Modell, wann es die vollständige SKILL.md liest. Der Abschnitt zu den Frontmatter-Metadaten in SKILL.md formuliert es noch direkter: name und description sind entscheidend dafür, dass das Modell Skills findet und den richtigen auswählt.

In den Repositorys des Agents SDK ist description damit einer der wichtigsten Anhaltspunkte für die Auswahl, bevor Codex den restlichen Inhalt des Skills gelesen hat.

Ein konkretes Beispiel liefert code-change-verification.

Zu ungenau:

description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.

Genauer ist die tatsächlich verwendete Beschreibung:

description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.

Die kürzere Fassung sagt Codex bereits, was der Skill tut. Offen bleibt, wann er anzuwenden ist, welche Änderungen ihn auslösen sollen und ob die Prüfungen im jeweiligen Fall vorgeschrieben sind. Die genauere Fassung beantwortet alle drei Fragen.

Dasselbe Muster findet sich bei pr-draft-summary.

Zu ungenau:

description: Create a PR title and draft description for a pull request.

Genauer ist die tatsächlich verwendete Beschreibung:

description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.

Auch hier hilft die tatsächliche Beschreibung Codex bei der Auswahl. Aus ihr geht hervor:

  • Der Skill kommt am Ende einer Aufgabe zum Einsatz.
  • Er ist für wesentliche Änderungen vorgesehen und wird nicht bei jedem einzelnen Chat-Beitrag aufgerufen.
  • Die Ausgabe ist ein direkt für den Pull Request verwendbarer Block und geht über eine Zusammenfassung in Fließtext hinaus.

Unsere Erfahrung mit diesen Repositorys zeigt, dass es sich lohnt, Zeit in description zu investieren. Wenn Codex die Skills nicht zuverlässig auswählt, überarbeite zuerst die Metadaten, bevor du weiteren Code hinzufügst.

Wiederkehrende Schritte in Skripte auslagern

Als Nächstes stellt sich die Frage, welche Aufgaben das Modell übernehmen soll und welche in ein Skript gehören.

Diese Aufteilung hat sich bewährt:

  • Das Modell interpretiert, vergleicht und berichtet über die Ergebnisse.
  • Deterministische, wiederkehrende Shell-Aufgaben gehören in scripts/.

Das entspricht den öffentlichen Empfehlungen. Laut der Dokumentation zur Anpassung von Codex können Skills Codex ausführliche Anweisungen, Skripte und Referenzmaterial für wiederholbare Workflows bereitstellen, ohne den Kontext von Anfang an unnötig zu vergrößern. So kann Codex die Teile einer Aufgabe übernehmen, bei denen es auf den Kontext ankommt, und bei Bedarf Skripte für die deterministischen Schritte hinzuziehen. Der Cookbook-Beitrag zu Skills in der OpenAI API empfiehlt außerdem, Skill-Skripte wie kleine CLIs zu gestalten. Sie lassen sich über die Befehlszeile starten, liefern eine deterministische Ausgabe auf stdout, brechen bei Fehlern mit klaren Nutzungshinweisen oder Fehlermeldungen ab und schreiben Ergebnisse bei Bedarf in Dateien mit bekannten Pfaden.

In den Repositorys des Agents SDK setzen wir das Modell dort ein, wo seine Fähigkeit zur Beurteilung gefragt ist, zum Beispiel um:

  • aus dem Quellcode das beabsichtigte Verhalten abzuleiten
  • Protokolle mit diesem Verhalten abzugleichen
  • zu beurteilen, ob ein Release-Diff ein tatsächliches Kompatibilitätsrisiko enthält
  • einen Befund so zu erklären, dass das Team weiß, was zu tun ist

Skripte übernehmen die zugehörigen Arbeitsschritte, zum Beispiel:

  • die vorgeschriebenen Prüfbefehle des Repositorys in einer festen Reihenfolge ausführen
  • Beispiele starten, für jedes Beispiel Protokolle sammeln und bei Fehlern Dateien für einen erneuten Lauf schreiben
  • vor der Prüfung der Release-Bereitschaft den Tag des vorherigen Releases abrufen
  • Hilfsbefehle wie start, stop, status, logs, tail, collect und rerun bereitstellen, damit sich derselbe Workflow leicht wiederholen lässt

Wenn das Modell dieselbe Folge von Shell-Befehlen jedes Mal neu ermitteln muss, gehört sie in der Regel in ein Skript. Wo Kontext, Abwägung oder Erklärung gefragt sind, sollte das Modell zuständig bleiben.

Integrationstests automatisieren

Automatisierte Integrationstests gehören in beiden Repositorys zu den nützlichsten Workflows. Sie decken zwei verwandte Aufgaben ab. Beide Repositorys prüfen die enthaltenen Beispiele automatisch. Das JavaScript-Repository prüft zusätzlich, ob veröffentlichte Pakete weiterhin funktionieren, wenn man sie so installiert, wie es in der Praxis üblich ist.

Vor diesem Setup mussten wir die Beispiele teilweise von Hand prüfen. Die Beispiele ließen sich ausführen, aber zum Schluss musste oft jemand die Protokolle durchsehen oder anhand der Ausgabe beurteilen, ob das Ergebnis stimmte. Für ein einzelnes Beispiel ist das machbar. In einem wachsenden SDK-Repository stößt man damit schnell an Grenzen.

Die erste Aufgabe übernimmt examples-auto-run. Den Runner gab es allerdings schon vor dem Skill. Um die Prüfung der Beispiele überhaupt zu automatisieren, mussten wir zunächst in beiden Repositorys die Voraussetzungen dafür schaffen, dass Beispiele ohne Benutzereingriff laufen. Die Beispielskripte brauchten einen automatischen Modus, auch wenn sie normalerweise Eingaben oder Genehmigungen anfordern.

Dazu gehörten folgende Vorarbeiten:

  • häufige interaktive Abfragen automatisch beantworten
  • HITL-, MCP-, apply_patch- und Shell-Aktionen automatisch genehmigen, sofern der Runner dies unterstützt
  • Beispiele, die sich noch nicht automatisieren lassen, in einer Liste führen und automatisch überspringen, etwa Realtime-Beispiele oder Beispiele für Next.js-Apps, die zusätzliche Laufzeitkonfiguration benötigen
  • für jeden Beispiellauf strukturierte Protokolle schreiben
  • Dateien für erneute Läufe erzeugen, damit sich fehlgeschlagene Beispiele einzeln wiederholen lassen

Auf dieser Grundlage haben wir den Workflow als Skill organisiert. So lässt er sich wiederverwenden und einfach aufrufen. Im Python-Repository ruft examples-auto-run den Befehl uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ... auf. Im JavaScript-Repository führt der Skill zunächst die Build-Prüfungen aus und startet dann pnpm examples:start-all im automatischen Modus. Für jedes Beispiel gibt es ein eigenes Protokoll und die Möglichkeit, den Lauf zu wiederholen.

Damit die Prüfung aussagekräftiger wird, führt der Runner die Beispiele aus und hält stdout und stderr für jedes Beispiel in einem eigenen Protokoll fest. Der Skill weist Codex dann an, die Protokolle einzeln mit dem Quellcode abzugleichen:

  • Quellcode und Kommentare des Beispiels lesen
  • den beabsichtigten Ablauf daraus ableiten
  • das zugehörige Protokoll öffnen
  • das beabsichtigte Verhalten mit der tatsächlichen Ausgabe auf stdout und stderr vergleichen
  • diesen Abgleich für jedes erfolgreich ausgeführte Beispiel durchführen, statt nur eine Stichprobe zu prüfen

Das ist genauer und flexibler, als die Korrektheit im Skript mit einer festen Assertion zu prüfen. Ein erfolgreicher Exit-Code ist ein hilfreiches Signal. Bei Beispielen, die echte APIs aufrufen, Tools verwenden oder strukturierte Ausgaben erzeugen, reicht er jedoch nicht aus. Indem wir die tatsächliche Ausgabe zuerst protokollieren und anschließend sorgfältig mit dem Quellcode abgleichen, können wir jedes Beispiel an seinem beabsichtigten Verhalten messen.

Im JavaScript-Repository übernimmt der separate Skill integration-tests die zweite Aufgabe. Dieser Workflow geht über die Ausführung der Beispiele direkt aus dem Quellcode hinaus. Er veröffentlicht die Pakete in einer lokalen Verdaccio-Registry und testet ihre Installation und Ausführung in mehreren Umgebungen, darunter Node.js, Bun, Deno, Cloudflare Workers und eine React-App mit Vite. So fallen Probleme auf, die ein Beispiellauf im Repository nicht erfasst. Auf die Frage „Läuft das Beispiel im Repository?“ folgt eine zweite: „Verhält sich das Paket nach der Veröffentlichung, der Installation und der Integration in die Laufzeitumgebung weiterhin korrekt?“

An diesen Workflows lässt sich sehen, wie Skills, Skripte und das Urteilsvermögen des Modells zusammenspielen. Die Skripte sorgen für wiederholbare Läufe, halten die Ergebnisse fest und decken Installationswege ab, die von Hand mühsam zu prüfen wären. Anhand dieser Ergebnisse kann Codex Soll- und Ist-Verhalten genauer vergleichen, als es eine einfache skriptgesteuerte Prüfung mit dem Ergebnis „bestanden“ oder „fehlgeschlagen“ erlaubt.

Release-Prüfungen ergänzen

Auch bei der Vorbereitung von Releases hilft dieses Vorgehen.

In beiden Repositorys ermittelt der Workflow für die Release-Prüfung zunächst den Tag des vorherigen Releases und erstellt einen Diff zum aktuellen Stand von main. Anschließend prüft Codex diesen Diff auf:

  • Probleme mit der Abwärtskompatibilität öffentlicher APIs oder des nach außen sichtbaren SDK-Verhaltens
  • Regressionen, einschließlich kleinerer Abweichungen vom erwarteten Verhalten
  • fehlende Migrationshinweise oder ausstehende Aktualisierungen der Release Notes für Änderungen, die solche Hinweise erfordern

Anhand dieser Befunde beurteilt der Skill, ob das Release insgesamt bereit zur Veröffentlichung ist.

Ein Beispiel liefert openai/openai-agents-python#2480. Die Prüfung gibt insgesamt grünes Licht, weist aber ausdrücklich darauf hin, dass die Unterstützung für Python 3.9 entfällt und die Release Notes entsprechend ergänzt werden müssen:

Release readiness review (excerpt)

Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.

Scope summary:

- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
  `src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
  `pyproject.toml`, `uv.lock`.

Python 3.9 support removed

- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
  0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
  the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
  packaging metadata remains `>=3.10`.

Der Skill legt auch fest, wie die Entscheidung über die Freigabe zustande kommt. Die Prüfung geht zunächst davon aus, dass das Release veröffentlicht werden kann. Sie blockiert die Freigabe nur, wenn der Diff konkrete Belege für ein tatsächliches Problem liefert. Bei jeder blockierten Freigabe muss eine Checkliste angeben, was zu tun ist, um die Blockierung aufzuheben. Das macht das Ergebnis leichter nutzbar. Grün bedeutet, dass im Diff kein Problem gefunden wurde, das die Veröffentlichung verhindert. Bei einer Blockierung sind das Problem und der nächste Schritt klar benannt.

Das ist hilfreicher als die allgemeine Bitte „Prüfe das Release“. Das Modell muss einen konkreten Diff beurteilen und erklären, was das Ergebnis für die Veröffentlichung bedeutet. Kann das Release veröffentlicht werden, soll es das klar sagen. Andernfalls soll es genau angeben, woran es das Problem erkennt und was als Nächstes zu tun ist.

Workflows in der CI ausführen

Sobald sich ein Skill lokal bewährt hat, lässt sich derselbe Workflow mit der Codex GitHub Action leicht in der CI automatisieren. Das funktioniert am besten, wenn der lokale Workflow bereits stabil läuft. Beim manuellen Einsatz findest du Fehler in den Anweisungen, verfeinerst die Skripte und entdeckst die Ausnahmefälle, die in der Praxis auftreten.

Bei öffentlichen Repositorys ist die Wahl der Auslöser genauso wichtig wie der Skill selbst. Die Sicherheitscheckliste für die GitHub Action empfiehlt, den Kreis der Personen zu beschränken, die den Workflow starten dürfen. Bevorzuge vertrauenswürdige Ereignisse oder ausdrückliche Genehmigungen. Bereinige Prompt-Eingaben aus Pull Requests, Commits, Issues oder Kommentaren, schütze OPENAI_API_KEY mit drop-sudo oder einem Benutzerkonto ohne erhöhte Rechte und führe Codex als letzten Schritt des Jobs aus.

Wenn ein Workflow Schreibzugriff hat und nicht vertrauenswürdige öffentliche Eingaben verarbeitet, liegt das Risiko meist darin, wie er ausgelöst wird, wie er Eingaben behandelt und mit welchen Rechten der Skill zur Laufzeit arbeitet.

Pull Requests mit Codex prüfen

Skills tragen in diesen Repositorys zur Produktivität bei. Einen weiteren Beitrag leistet die automatische Überprüfung von Pull Requests mit Codex auf GitHub.

Seit diese Funktion verfügbar ist, unterstützt uns Codex bei der Prüfung der meisten Codeänderungen in diesen Repositorys. Wir setzen Codex dabei routinemäßig ein.

Bei klar umrissenen Programmfehlern, Regressionen und fehlenden Tests können wir uns in der Praxis inzwischen für die vorgeschriebene Prüfung auf Codex verlassen. Codex prüft wiederkehrende Fehlermuster zuverlässig. Dadurch entfällt bei kleinen Fehlerkorrekturen und routinemäßigen Verbesserungen ein wesentlicher Engpass.

Für andere Arten von Änderungen bleibt die Prüfung im Team wichtig.

Das Urteil von Menschen ist unverzichtbar, wenn die entscheidende Frage über „Ist dieser Code korrekt?“ hinausgeht und lautet: „Welche der möglichen Lösungen wählen wir, und wie veröffentlichen wir sie?“ Das betrifft unter anderem:

  • Änderungen an APIs oder der Architektur, bei denen es mehrere sinnvolle Entwürfe gibt und das zuständige Team ausdrücklich einen davon wählen muss
  • Verhaltensänderungen, die Erwartungen an das Produkt, Zusagen zur Abwärtskompatibilität oder Vorgaben zur Einführung betreffen
  • Entscheidungen über Benennung, Migration und Release-Kommunikation, bei denen es darauf ankommt, was für die Menschen, die das SDK nutzen oder daran mitarbeiten, am verständlichsten ist
  • Änderungen, die eine Abstimmung im Projekt oder zwischen Teams erfordern, etwa zum Umfang und zur Reihenfolge der Arbeiten oder zur Frage, was jetzt und was später veröffentlicht werden soll

Codex kann in all diesen Fällen zur Prüfung beitragen. Es bleibt aber sinnvoll, die Optionen direkt zu besprechen und die Entscheidung einem Menschen zu überlassen.

Auch diese Aufteilung lässt sich in AGENTS.md festhalten. Das Repository kann vorgeben, worauf Codex bei der Prüfung auf Korrektheit achten soll. Codex kann diese Vorgaben dann konsequent anwenden.

Auch das hat den Durchsatz deutlich erhöht. Bei Änderungen mit geringem Risiko müssen wiederkehrende Prüfungen und Validierungen nicht mehr jedes Mal warten, bis jemand Zeit dafür hat. Das Team kann sich auf Änderungen konzentrieren, bei denen mehr Kontext nötig ist und sein Urteil besonders zählt. Dadurch konnten wir offene Fehler und kleinere Funktionserweiterungen deutlich schneller bearbeiten.

Fazit

In den Repositorys des OpenAI Agents SDK funktionieren Skills am besten, wenn sie zum normalen Arbeitsablauf gehören.

AGENTS.md gibt vor, welche Workflows für Codex Pflicht sind. Aus description geht hervor, wann Codex sie auswählen soll. Unter scripts/ liegen die Skripte für die deterministischen Schritte. Das Modell übernimmt die Aufgaben, für die es auf den Kontext ankommt. Sobald ein Workflow lokal zuverlässig läuft, lässt er sich mit der Codex GitHub Action auch in der CI ausführen.

Damit ist im Entwicklungsalltag klarer festgelegt, wie wir in diesen Repositorys vorgehen, und die Abläufe sind verlässlicher. Kleine Verbesserungen können wir schneller veröffentlichen, weil die Überprüfung der Änderungen, die Release-Prüfung und die PR-Übergabe jetzt einem wiederholbaren Prozess folgen.

Weiterführende Ressourcen