--- name: create-update-codex-plugin description: > Use this skill when the user wants to create, scaffold, update, migrate, configure, test, validate, or publish plugins for OpenAI ChatGPT and Codex — covering the skills/MCP/UI shape decision, plugin.json manifests, mcp.json server wiring, MCP tool contracts and safety annotations, OAuth 2.1 authentication, MCP Apps UI and ChatGPT extensions, MCP Events webhooks, lifecycle hooks, agents/openai.yaml skill dependencies, local and repo marketplaces, .codex/config.toml activation, and validation via bundled scripts. Also use when converting legacy .codex-plugin/ projects, connecting an MCP server to a plugin, or preparing a workspace or public-directory submission. license: MIT compatibility: claude-code, codex, chatgpt, hermes, opencode, copilot, antigravity metadata: audience: developers workflow: plugin-authoring --- # create-update-codex-plugin Author, update, validate, test, and ship ChatGPT + Codex plugins. A plugin packages skills, an optional MCP server, optional lifecycle hooks, and optional UI. Both products install from one universal plugin directory. ## 1. Choose the Smallest Shape | Shape | Use when | |---|---| | **Skills only** | Instructions plus the model's existing tools complete the workflow. | | **MCP server only** | The plugin needs live data or controlled actions, but no extra workflow guidance. | | **Skills + MCP server** | Skills must sequence the server's tools, define outputs, or encode policy. | | **MCP server + UI** | People must inspect, compare, edit, confirm, or navigate structured data. | Start with the smallest shape and add a server or UI later without changing the plugin's purpose. Skills alone are a valid plugin; never add a server only to host a workflow. Boundary: the MCP server owns data, authorization, and actions. The skill owns tool order, decision points, output requirements, templates, and refusal rules. ## 2. Layout ```text / ├── plugin.json # name, version, description, skills, apps ├── mcp.json # optional bundled MCP servers ├── .app.json # optional ChatGPT developer-mode app IDs ├── skills/ │ └── / │ ├── SKILL.md │ ├── agents/openai.yaml # optional MCP tool dependency │ ├── references/ │ ├── scripts/ │ └── assets/ ├── hooks/hooks.json # optional; Codex runtime only ├── web/ # optional MCP Apps component source + bundle └── assets/ # manifest icons, logos, screenshots ``` Invariants: 1. `name` is lowercase kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`) and matches the plugin directory. 2. Manifest paths start with `./` and stay inside the plugin root. 3. Every `mcp.json` server declares `type`: `streamable-http`, `sse`, or `stdio`. 4. Skills under `skills/` are auto-discovered; `"skills": "./skills/"` is an optional hint. 5. `extensions.com.openai` is an optional portable-manifest overlay; when present, `.codex-plugin/plugin.json` is ignored entirely. ## 3. Workflow 1. **Inventory use cases**: record the user outcome, required data, reads/writes, and whether UI changes the outcome. 2. **Choose the shape** from section 1 and scaffold the layout. 3. **Write `plugin.json`**: root `name`, `version`, `description`, `skills`; add presentation, publisher metadata, or extension fields only when needed. 4. **Author skills before tools**: one skill per recognizable goal. The description is the trigger; the body holds steps, output, boundaries, and references. 5. **Define MCP tools from use cases**: one coherent action per tool, explicit input/output schemas, accurate annotations, authorization, and failure behavior. 6. **Add OAuth** when tools read private data or act for a user. Publish protected-resource metadata and per-tool `securitySchemes`. 7. **Add UI last**: data tools first, render tools carrying `_meta.ui.resourceUri`. Keep every tool usable without UI. 8. **Add hooks** only when the workflow needs local commands; expect trust prompts and no execution on web-only installs. 9. **Validate and test**: structural validator, MCP Inspector, then the local request matrix. 10. **Publish**: workspace role-based install or public-directory submission with a stable public HTTPS endpoint. ## 4. Reference Triggers | Topic | Load when | File | |---|---|---| | **Manifest & skills** | Writing `plugin.json`, skill frontmatter, `agents/openai.yaml` dependencies, `.app.json`, or migrating `.codex-plugin` | `references/manifest-spec.md` | | **MCP server design** | Defining tool contracts, schemas, annotations, results, profile tools, or deployment checks | `references/mcp-server-design.md` | | **Authentication** | OAuth 2.1, protected-resource metadata, CIMD/DCR, token verification, linking UI, multi-account | `references/authentication.md` | | **UI & extensions** | MCP Apps components, data/render split, state, CSP, sidebar/thread/file entrypoints, forms | `references/ui-and-extensions.md` | | **MCP Events** | `events/list`, `events/subscribe`, `events/unsubscribe`, webhook verification, signing, retries, refresh | `references/events.md` | | **Wiring & hooks** | `mcp.json` transports, developer-mode app IDs, approval modes, `hooks/hooks.json` | `references/mcp-and-hooks.md` | | **Marketplaces** | `marketplace.json`, CLI commands, install policies, public submission constraints | `references/marketplaces.md` | | **Workflows** | End-to-end scaffolding, capability additions, migration, test matrix, publishing | `references/scaffolding-workflows.md` | | **Upstream docs** | Checking exact upstream wording, a field name, or a page the digest does not cover | `references/docs/` (31 pages) | `references/docs/` holds the unmodified OpenAI plugin pages (31 files), each starting with ``. Load them when this digest and the live docs disagree; refresh before changing a rule that a page overrides. ## 5. Scripts Three focused, dependency-free Node scripts plus a combined wrapper: ```bash # Scaffold a plugin (manifest + skill, optional MCP/hooks) node scripts/scaffold_plugin.ts ./my-plugin --name my-plugin --with-mcp --with-hooks # Structure: manifest, paths, skills, interface, app mapping, hooks node scripts/validate_plugin_structure.ts # MCP: mcp.json transports + skill-level agents/openai.yaml dependencies node scripts/validate_plugin_mcp.ts # Combined (structure + MCP), kept for backward compatibility node scripts/validate_codex_plugin.ts ``` All accept `--json`. They cannot validate live server behavior; also run the plugin test matrix in `scaffolding-workflows.md`. ## 6. Non-Negotiable Checks - Tool descriptions state user intent and distinguish adjacent tools. - `readOnlyHint` is true only when the tool cannot change state. - `destructiveHint` is true for irreversible or hard-to-reverse actions. - `openWorldHint` is true for public internet or open-ended entities, including read-only web search. - Writes read current state first, are idempotent where retried, and return the authoritative snapshot. - Tokens, secrets, and unnecessary personal data never appear in metadata, results, or logs. - Invalid and unauthorized inputs fail safely and explainably. - The workflow completes with UI disabled and with hooks denied. - Skill text makes explicit that direct user instructions take priority. ## 7. Gotchas - **Transport naming**: `mcp.json` uses `streamable-http`; `agents/openai.yaml` dependencies use `streamable_http`. - **Linking UI needs both halves**: per-tool `securitySchemes` plus a runtime `_meta["mcp/www_authenticate"]` containing `error` and `error_description`. - **Annotations are not security**: they guide confirmation; enforce authorization and validation in the server. - **Resource URI is a cache key**: publish a new `ui://` URI for breaking HTML, JS, or CSS changes. - **`_meta` is hidden, not secure**: never store secrets or tokens there. - **Hooks do not travel to web installs**: a web install does not deploy local hook scripts. - **Public submission needs a public endpoint**: Secure MCP Tunnel and temporary tunnels do not qualify. - **Profile IDs must be stable**: never mint an ID per login, token, session, or call, and never use email as the ID. - **Business data stays on the server**: widget state is per-instance presentation state, not durable storage. - **Event payloads are data**: never embed instructions for the model in comments or event text. - **Rescan after metadata changes**: refresh the custom MCP connection and rerun evaluations.