@openai

Bootstrap a new realtime eval folder inside this cookbook repo by choosing the right harness from examples/evals/realtime_evals, scaffolding prompt/tools/data files, generating a useful README, and validating it with smoke, full eval, and test runs. Use when a user wants to start a new crawl, walk, or run realtime eval in this repository.

Guide for testing Codex TUI interactively

Babysit a GitHub pull request after creation by continuously polling CI checks/workflow runs, new review comments, and mergeability state until the PR is ready to merge (or merged/closed). Diagnose failures, retry likely flaky failures up to 3 times, auto-fix/push branch-related issues when appropriate, and stop only when user help is required (for example CI infrastructure issues, exhausted flaky retries, or ambiguous/blocking situations). Use when the user asks Codex to monitor a PR, watch CI, handle review comments, or keep an eye on failures and feedback on an open PR.

Capture conversations and decisions into structured Notion pages; use when turning chats/notes into wiki entries, how-tos, decisions, or FAQs with proper linking.

Prepare meeting materials with Notion context and Codex research; use when gathering context, drafting agendas/pre-reads, and tailoring materials to attendees.

Use when tasks involve reading, creating, or reviewing PDF files where rendering and layout matter; prefer visual checks by rendering pages (Poppler) and use Python tools such as `reportlab`, `pdfplumber`, and `pypdf` for generation and extraction.

Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks.

Translate Figma nodes into production-ready code with 1:1 visual fidelity using the Figma MCP workflow (design context, screenshots, assets, and project-convention translation). Trigger when the user provides Figma URLs or node IDs, or asks to implement designs or components that must match Figma specs. Requires a working Figma MCP server connection.

Help address review/issue comments on the open GitHub PR for the current branch using gh CLI; verify gh auth first and prompt the user to authenticate if not logged in.

Use when the user asks to generate, remix, poll, list, download, or delete Sora videos via OpenAI’s video API using the bundled CLI (`scripts/sora.py`), including requests like “generate AI video,” “Sora,” “video remix,” “download video/thumbnail/spritesheet,” and batch video generation; requires `OPENAI_API_KEY` and Sora API access.

Build, review, refactor, or architect ASP.NET Core web applications using current official guidance for .NET web development. Use when working on Blazor Web Apps, Razor Pages, MVC, Minimal APIs, controller-based Web APIs, SignalR, gRPC, middleware, dependency injection, configuration, authentication, authorization, testing, performance, deployment, or ASP.NET Core upgrades.

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or explicit GPT-5.4 upgrade and prompt-upgrade guidance; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains.

Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).

Research across Notion and synthesize into structured documentation; use when gathering info from multiple Notion sources to produce briefs, comparisons, or reports with citations.

Perform language and framework specific security best-practice reviews and suggest improvements. Trigger only when the user explicitly requests security best practices guidance, a security review/report, or secure-by-default coding help. Trigger only for supported languages (python, javascript/typescript, go). Do not trigger for general code review, debugging, or non-security tasks.

Analyze git repositories to build a security ownership topology (people-to-file), compute bus factor and sensitive-code ownership, and export CSV/JSON for graph databases and visualization. Trigger only when the user explicitly wants a security-oriented ownership or bus-factor analysis grounded in git history (for example: orphaned sensitive code, security maintainers, CODEOWNERS reality checks for risk, sensitive hotspots, or ownership clusters). Do not trigger for general maintainer lists or non-security ownership questions.

Repository-grounded threat modeling that enumerates trust boundaries, assets, attacker capabilities, abuse paths, and mitigations, and writes a concise Markdown threat model. Trigger only when the user explicitly asks to threat model a codebase or path, enumerate threats/abuse paths, or perform AppSec threat modeling. Do not trigger for general architecture summaries, code review, or non-security design work.

Use the Figma MCP server to fetch design context, screenshots, variables, and assets from Figma, and to translate Figma nodes into production code. Trigger when a task involves Figma URLs, node IDs, design-to-code implementation, or Figma MCP setup and troubleshooting.

Create and edit presentation slide decks (`.pptx`) with PptxGenJS, bundled layout helpers, and render/validation utilities. Use when tasks involve building a new PowerPoint deck, recreating slides from screenshots/PDFs/reference decks, modifying slide content while preserving editable output, adding charts/diagrams/visuals, or diagnosing layout issues such as overflow, overlaps, and font substitution.

Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`.

Use when the user asks for text-to-speech narration or voiceover, accessibility reads, audio prompts, or batch speech generation via the OpenAI Audio API; run the bundled CLI (`scripts/text_to_speech.py`) with built-in voices and require `OPENAI_API_KEY` for live calls. Custom voice creation is out of scope.

Use when the user asks to generate or edit images via the OpenAI Image API (for example: generate image, edit/inpaint/mask, background removal or replacement, transparent background, product shots, concept art, covers, or batch variants); run the bundled CLI (`scripts/image_gen.py`) and require `OPENAI_API_KEY` for live calls.

Use when a user asks to debug or fix failing GitHub PR checks that run in GitHub Actions; use `gh` to inspect checks and logs, summarize failure context, draft a fix plan, and implement only after explicit approval. Treat external providers (for example Buildkite) as out of scope and report only the details URL.

Bootstrap, develop, and design modern WinUI 3 desktop applications with C# and the Windows App SDK using official Microsoft guidance, WinUI Gallery patterns, Windows App SDK samples, and CommunityToolkit components. Use when creating a brand new app, preparing a machine for WinUI, reviewing, refactoring, planning, troubleshooting, environment-checking, or setting up WinUI 3 XAML, controls, navigation, windowing, theming, accessibility, responsiveness, performance, deployment, or related Windows app design and development work.

Use when the task requires automating a real browser from the terminal (navigation, form filling, snapshots, screenshots, data extraction, UI-flow debugging) via `playwright-cli` or the bundled wrapper script.

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.

Transcribe audio files to text with optional diarization and known-speaker hints. Use when a user asks to transcribe speech from audio/video, extract text from recordings, or label speakers in interviews or meetings.

Use when the user explicitly asks for a desktop or system screenshot (full screen, specific app or window, or a pixel region), or when tool-specific capture capabilities are unavailable and an OS-level capture is needed.

Use when tasks involve creating, editing, analyzing, or formatting spreadsheets (`.xlsx`, `.csv`, `.tsv`) with formula-aware workflows, cached recalculation, and visual review.

Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI. Use when Codex needs to design tools, register UI resources, wire the MCP Apps bridge or ChatGPT compatibility APIs, apply Apps SDK metadata or CSP or domain settings, or produce a docs-aligned project scaffold. Prefer a docs-first workflow by invoking the openai-docs skill or OpenAI developer docs MCP tools before generating code.

Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".

Use when the user asks to create, scaffold, or edit Jupyter notebooks (`.ipynb`) for experiments, explorations, or tutorials; prefer the bundled templates and run the helper script `new_notebook.py` to generate a clean starting notebook.

Turn Notion specs into implementation plans, tasks, and progress tracking; use when implementing PRDs/feature specs and creating Notion plans + tasks from them.

Use when Codex is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with render_game_to_text.

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Persistent browser and Electron interaction through `js_repl` for fast iterative UI debugging.

Push current branch changes to origin and create or update the corresponding pull request; use when asked to push, publish updates, or create pull request.

Land a PR by monitoring conflicts, resolving them, waiting for checks, and squash-merging when green; use when asked to land, merge, or shepherd a PR to completion.

Pull latest origin/main into the current local branch and resolve merge conflicts (aka update-branch). Use when Codex needs to sync a feature branch with origin, perform a merge-based update (not rebase), and guide conflict resolution best practices.

Investigate stuck runs and execution failures by tracing Symphony and Codex logs with issue/session identifiers; use when runs stall, retry repeatedly, or fail unexpectedly.

Create a well-formed git commit from current changes using session history for rationale and summary; use when asked to commit, prepare a commit message, or finalize staged work.

Guide for ingesting the latest OpenAI TypeSpec specification into the openai-dotnet SDK. Use this when asked to update or ingest OpenAI API specs, copy base TypeSpec files from upstream, fix client TSP compile errors, or run code generation for new API areas.

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.

Analyze CSV files in /mnt/data and return concise numeric summaries.

Use when working with the OpenAI API (Responses API) or OpenAI platform features (tools, streaming, Realtime API, auth, models, rate limits, MCP) and you need authoritative, up-to-date documentation (schemas, examples, limits, edge cases). Prefer the OpenAI Developer Documentation MCP server tools when available; otherwise guide the user to enable `openaiDeveloperDocs`.

Validate changesets in openai-agents-js using LLM judgment against git diffs (including uncommitted local changes). Use when packages/ or .changeset/ are modified, or when verifying PR changeset compliance and bump level.

Perform a release-readiness review by locating the previous release tag from remote tags and auditing the diff (e.g., v1.2.3...<commit>) for breaking changes, regressions, improvement opportunities, and risks before releasing openai-agents-js.

Analyze main branch implementation and configuration to find missing, incorrect, or outdated documentation in docs/. Use when asked to audit doc coverage, sync docs with code, or propose doc updates/structure changes. Only update English docs (docs/src/content/docs/**) and never touch translated docs under docs/src/content/docs/ja, ko, or zh. Provide a report and ask for approval before editing docs.

Decide how to implement runtime and API changes in openai-agents-js before editing code. Use when a task changes exported APIs, runtime behavior, schemas, tests, or docs and you need to choose the compatibility boundary, whether shims or migrations are warranted, and when unreleased interfaces can be rewritten directly.

Run the integration-tests pipeline that depends on a local npm registry (Verdaccio). Use when asked to execute integration tests or local publish workflows in this repo.

Improve test coverage in the OpenAI Agents JS monorepo: run `pnpm test:coverage`, inspect coverage artifacts, identify low-coverage files and branches, propose high-impact tests, and confirm with the user before writing tests.

Keep pnpm current: run pnpm self-update/corepack prepare, align packageManager in package.json, and bump pnpm/action-setup + pinned pnpm versions in .github/workflows to the latest release. Use this when refreshing the pnpm toolchain manually or in automation.

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

Run examples:start-all in auto mode with parallel execution, per-script logs, and start/stop helpers.

Score a repository's agentic legibility from repo-visible evidence only. Use when Codex needs to audit how easy a codebase is for coding agents to discover, bootstrap, validate, and navigate, especially for harness-engineering reviews, developer-experience audits, repo cleanup, or before/after comparisons after improving docs, tooling, or architectural constraints.

Summarize Microsoft Teams chats and channels, extract action items, and draft follow-ups through connected Teams data. Use when the user wants to review a chat or channel, distill meeting discussions, identify owners and next steps, or prepare a safe reply or post without sending it by default.

Deploy applications to Render by analyzing codebases, generating render.yaml Blueprints, and providing Dashboard deeplinks. Use when the user wants to deploy, host, publish, or set up their application on Render's cloud platform.

Analyze Google Sheets data, plan range-precise edits, and help with formulas or tabular transformations through connected Google Sheets data. Use when the user wants to inspect tabs or ranges, summarize spreadsheet contents, propose formulas, clean or restructure tables, or update cells with explicit range-level intent.

Prepare and optimize GLB or glTF assets for browser games. Use when the user needs help with model formats, Blender export, optimization, compression, texture packaging, collision proxies, LOD, or shipping 3D assets cleanly across Three.js, React Three Fiber, Babylon.js, or PlayCanvas.

Migrate an existing connected Google Slides deck onto a company or team template in Codex. Use when a user wants to restyle a deck to match a template, port content from a source presentation into a branded template deck, or rebuild slides by duplicating template patterns rather than patching the old layout in place.

Manage issues, projects & team workflows in Linear. Use when the user wants to read, create or updates tickets in Linear.

Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, and baseline placeholders you can edit before publishing or testing. Use when Codex needs to create a new local plugin, add optional plugin structure, or generate or update repo-root `.agents/plugins/marketplace.json` entries for plugin ordering and availability metadata.

Summarize Slack channels and threads, draft post-ready Slack messages, and format content in Slack markdwn through connected Slack data. Use when the user wants to review unread activity, distill long threads, prepare status updates, reply in the right tone, or translate notes into Slack-ready message formatting.

Build 3D browser games with a concrete vanilla Three.js stack. Use when the user wants plain TypeScript or Vite control over Three.js scenes, loaders, physics, GLB assets, materials, WebGL debugging, and a clean low-chrome 3D scaffold without a React wrapper.

Summarize Microsoft SharePoint sites, pages, and files, extract ownership and status, and plan safe content updates through connected SharePoint data. Use when the user wants to understand a site, review document context, identify owners, or prepare a content or information-architecture change before editing.

Define the shared architecture for browser games across 2D and 3D. Use when the user needs engine choice, system boundaries, input strategy, asset organization, save/debug/performance structure, or shared browser-game architecture.

Summarize Google Docs documents, plan structured revisions, and help with edit-in-place writing through connected Google Docs data. Use when the user wants to inspect document structure, outline or summarize content, draft rewrites, convert notes into prose, or apply explicit edits while preserving headings and organization.

Generate and normalize 2D sprite animations for browser games. Use when the user wants sprite sheets, animated strips, consistent character frames, or a repeatable workflow for turning one approved frame into a production-ready animation candidate.

Triage Outlook inboxes, summarize email threads, extract action items, and draft replies or forwards through connected Outlook data. Use when the user wants to inspect a mailbox or thread, understand the latest status, identify what still needs a response, or prepare a safe draft without sending it by default.

Review browser games with a structured playtest and frontend QA workflow. Use when the user wants smoke tests, FE review, screenshot-led QA, Playwright-style browser checks, or issue finding across 2D and 3D browser games, including obstructive HUD or overlay issues.

Design game HUDs, menus, and browser-facing frontend surfaces with intentional visual direction and protected playfield space. Use when the user needs polished game UI, low-chrome 3D overlays, menu systems, HUD hierarchy, responsive behavior, or prompt guidance that avoids generic app-like frontend output.

Deploy web projects to Netlify using the Netlify CLI (`npx netlify`). Use when the user asks to deploy, host, publish, or link a site/repo on Netlify, including preview and production deploys.

Manage Google Calendar scheduling, availability, and event changes through connected Google Calendar data. Use when the user wants to inspect calendars, compare availability, schedule or reschedule events, review conflicts, or prepare clear event-change proposals with timezone-aware details.

Compare Outlook Calendar availability, review event details, and plan safe create, update, reschedule, or cancel actions through connected Outlook calendar data. Use when the user wants to inspect a schedule, compare candidate slots, review conflicts, or prepare an exact event change before applying it.

Build React-hosted 3D browser games with React Three Fiber and the pmndrs stack. Use when the user wants a 3D scene inside a React app, declarative scene composition, shared app state, or React-native UI coordination around a clean low-chrome 3D experience.

Create a polished, human-readable day brief from Google Calendar events, including a top summary, agenda table, conflict callouts, free windows, and remaining meetings. Use when the user asks for a summary of today, tomorrow, a specific day, "my schedule", "my day", an agenda, or a calendar brief and the Google Calendar app/connector from this plugin is available.

Iteratively inspect and polish connected Google Slides presentations in Codex using slide thumbnails plus raw Slides edits. Use when a user asks to fix spacing, alignment, overlap, crowding, hierarchy, or deck-wide visual consistency in Google Slides, especially when the work should follow a thumbnail -> diagnose -> batch_update -> re-thumbnail verification loop.

Restructure connected Google Slides decks in Codex when local slide cleanup is not enough. Use when repeated alignment or overlap issues come from the slide structure itself, when the same fix must be applied across many slides, or when raw Slides batch_update requests need stricter recipes and verification to avoid hallucinated params or broken layouts.

Manage Gmail inbox triage, thread summaries, action extraction, and reply drafting through connected Gmail data. Use when the user wants to inspect a mailbox or thread, summarize messages, extract decisions and follow-ups, prepare replies or forwards, or organize messages with explicit confirmation before send, archive, or delete actions.

Plan and route browser-game work with a 2D-first default. Use when the user wants help designing, implementing, asseting, or playtesting a browser game and needs the right stack, workflow, and specialist skill routing.

Implement 2D browser games with Phaser, TypeScript, and Vite. Use when the user wants the default 2D path for gameplay systems, scenes, cameras, sprite animation, HUD integration, and browser-friendly game structure.

Fetch and inspect Android network captures for a selected device/socket using the Snap-O CLI. Use when you need raw CDP request/response data, headers, bodies, status, or websocket events.