Skip to content

phuryn/product-engineering / app-stack/skills/chatgpt-plugin

chatgpt-plugin

Verified

Before building, submitting or changing a ChatGPT plugin or Apps SDK app: get it through OpenAI's directory review (auth, package, OAuth, data rules, portal).

ChatGPT plugin

Verify the plugin against directory requirements before its first submission. ChatGPT and Codex share OpenAI's plugin directory. This skill works with any remote MCP server, in any language, behind any OAuth provider or none. The rules use OpenAI's own pages, read on 2026-10-26, and product submissions.

OpenAI's pages, each available as Markdown by appending .md: developers.openai.com/plugins/deploy/submission, /deploy/submission-errors, /deploy/app-review, /plugin-guidelines, /build/plugins, /build/auth, /reference and /deploy/connect-chatgpt.

What binds, in order

  1. Follow OpenAI's current pages when they disagree with this skill. They change without notice and contradicted each other in six places (read 2026-10-26; § Where OpenAI's pages disagree). Read them again before every upload and every submission, and record the date. Where this skill and a page disagree, the page wins and this skill gets a dated correction.
  2. Use this skill for what OpenAI's pages leave out. It covers what the portal and reviewers actually did.
  3. Keep the server's own engineering rules for MCP implementation. This skill covers only what ChatGPT adds to an MCP server. The route, tool descriptions, output schemas and their tests are the mcp-server skill's, if you use this collection; this skill does not need it.

Two ways in

Custom connectorDirectory plugin
How a user gets itadds the server's URL in ChatGPT: Plugins → + → Add custom MCP server (workspace policy permitting)finds it in the directory, by its link or by name
What you shipa remote MCP serverthe server and a ZIP package: manifest, mcp.json, at least one skill, assets, review materials
Sign-inwhatever the server's OAuth discovery offersdeclared in the package: none, OAuth, or both
Reviewnoneautomated scans, then people, then daily rescans for as long as it is listed

Connect it as a custom connector against production first. A working custom connector is most of the way there. The directory adds the package, data rules, publishing identity and review. Record the review video this way too. Before approval, the plugin itself runs only as a local install in ChatGPT's desktop app or Codex, never on the web.

Decide these first, and record them

DecisionThe defaultWhy it is decided before the first uploadWhere
Who signs inOAuth on the server the product already has, if it has accountsThe portal reads authentication from each upload's mcp.json, but an existing connection can lock itreferences/package.md § mcp.json · references/portal-and-review.md § Create the draft
Which endpointOne per plugin, on a host you will keepOnly one MCP server can be connected per plugin, and the origin (scheme, host, port) can never change: a new origin is a new pluginreferences/portal-and-review.md § After publication
Which toolsThe everyday actions, minus anything that takes or returns a secretOpenAI's restricted data includes API keys and passwords, and the review reads the server's own tool list. A server whose setup tools take provider keys needs a narrowed list on a route of its ownreferences/tools-and-data.md § Restricted data
Who publishesThe legal entity the privacy policy and terms name, verified on the OpenAI PlatformThe directory shows the verified identity chosen when the draft is created, whatever the ZIP says; it must match the legal pagesreferences/portal-and-review.md § Before the first upload
Which projectOne with global data residencyProjects with EU data residency cannot submit plugins with MCP serverssame
Where it is availableEverywhere (publication.countries omitted)An allowlist in the package applies when the plugin is publishedreferences/package.md § plugin.json

The rules every submission meets

  • Authentication is declared in mcp.json, per server, before the first upload. For a server with no sign-in, never complete an OAuth sign-in in the portal: the connection it makes is kept. references/package.md § mcp.json.
  • Discovery answers the portal's scanner. It called from outside ChatGPT's published address ranges (observed 2026-10-23). Gate tool calls, not initialize and tools/list. references/server-and-auth.md § A surface with no sign-in.
  • Every request's params may carry _meta, and the server accepts it. ChatGPT sends user, session, location, trace and call ids on every tool call (observed 2026-10-27). OpenAI documents a locale on initialize. A parser refusing unknown keys there would refuse every one of those calls. references/server-and-auth.md § What every request carries.
  • No tool asks for a secret and no reply contains one. No reply carries a field the request did not need. references/tools-and-data.md.
  • The privacy policy names every field a reply returns. A test holds the policy and replies equal both ways. Include nested fields and error replies. references/tools-and-data.md § The privacy policy.
  • Every tool sets readOnlyHint, destructiveHint and openWorldHint explicitly. Set readOnlyHint, destructiveHint and openWorldHint on every tool. An irreversible effect is its own tool; an action stays destructive even when another tool can undo it. references/tools-and-data.md § Annotations.
  • Review materials travel in the ZIP; credentials never do. Five positive cases, three negative ones, the video's link and the release notes in plugin.json; the reviewer's account in the portal. references/package.md § plugin.json.
  • The ZIP is checked, then pinned to the package. python <skill dir>/scripts/check_package.py <package dir> --zip <zip> before every upload; a test in the product's suite holds the same byte-for-byte equality, because the portal reads only the ZIP and a ZIP rebuilt by hand goes stale.
  • Listing copy sells nothing. No pricing, trials or promotions; nothing that steers the model toward the plugin; no "MCP" or "Plugin" after the name. references/tools-and-data.md § Names, descriptions and copy.

The stage, in order

  1. Record each decision above in the product's decision log.
  2. Prove the production server works as ChatGPT calls it. Require _meta accepted, discovery open, OAuth meeting ChatGPT's client, the address check (if any) on the caller's own address. Connect it in ChatGPT as a custom connector against production and call every tool; record the date and what was called (references/server-and-auth.md).
  3. Narrow the tool list and test every returned field. Include the list narrowed to what may be listed, replies allowlisted at every depth, annotations, the privacy page's field inventory, and the tests that hold them (references/tools-and-data.md).
  4. Build and pin the full submission package. Include manifest, mcp.json, a skill that names the tools, assets, the five and three review cases taken from the routing evals' own file, the checker, and the ZIP pinned (references/package.md).
  5. Run routing evals against a local server; record video against production. Record the video in ChatGPT (references/server-and-auth.md § Testing before approval).
  6. Prepare a reviewer account when the server has sign-in. Give it sample data, no emailed or texted code, a plan on which every case succeeds (references/portal-and-review.md § Review information).
  7. Create the draft under the right identity and check authentication before connecting. Complete the draft under the right identity, the Authentication field checked before connecting, domain verification, the scan, review details, then the checklist in references/portal-and-review.md § Before you submit.
  8. Respond to the decision and keep live definitions working after publication. Then answer or appeal, publish when ready, and keep the live definitions working through every later deploy (references/portal-and-review.md § After publication).

Each rule's origin, the case that taught it, is in receipts.md beside this file; read it when a rule's edge is unclear.

How you can tell it worked

Every item the review checks was verified on the deployed build before submitting, and the review came back with no fix request on any of them.

Files

FileHoldsRead when
references/package.mdthe package's layout, every plugin.json field with its limit, mcp.json's authentication, the skill inside the package, what cannot be submitted, pinning the ZIPbuilding or changing the package
references/server-and-auth.mdwhat every ChatGPT request carries, what ChatGPT's OAuth client needs, per-tool securitySchemes, a surface with no sign-in, shared addresses, testing before approvalbuilding the endpoint, its OAuth or its address gate; testing it in ChatGPT
references/tools-and-data.mdrestricted data, response minimization, the privacy policy, annotations, names and copy, and the tests that hold themchoosing the tools, shaping replies, writing the privacy page
references/portal-and-review.mdthe account and identity, the draft, connecting and scanning, review information, the review, rejection and appeal, publishing, after publication, and the checklist before submittingin the portal; answering a review; changing a listed plugin
scripts/check_package.pychecks a package folder and its ZIP against the rules OpenAI states and the traps met; errors exit 1before every upload
scripts/test_check_package.pybuilds a valid package and breaks it one way at a timeafter every edit to the checker

Where OpenAI's pages disagree

Follow the stricter reading until OpenAI's pages agree. These were read on 2026-10-26; correct this list when they agree.

  • Keep one justification sentence per hint per tool ready. The guidelines say "Annotation justifications are no longer required." The submission-errors page still lists justification_required ("Every MCP tool annotation must include a justification") and a final-submission requirement of "a justification for each value on every MCP tool". Keep one sentence per hint per tool ready; it does not change the hint, which comes from the server.
  • Treat the origin as permanent and a path change as a support conversation. The submission page says "To change an existing MCP server's URL, contact support; the current update flow does not support URL changes." The review page says a new origin needs a new plugin and a new path goes through the normal new-version flow. Treat the origin as permanent and a path change as a support conversation that may not be needed.
  • Try a corrected ZIP first after a package rejection. The submission page says "For a rejected package, address the feedback and submit a corrected ZIP." A known issue can prevent updating a rejected plugin, according to OpenAI support (observed 2026-10-19), with a new plugin as the fallback. Try the corrected ZIP first.
  • Use lowercase letters, numbers and single hyphens for the package name. The submission page asks for "lowercase letters, numbers, and single hyphens"; the submission-errors page allows "ASCII letters, digits, _, or -". Use the first.
  • Keep the root description within 1,024 characters. "At most 4000 characters" on the submission page, "1,024 characters or fewer" on the submission-errors page. Keep it within 1,024; the checker does.
  • Ship no screenshots without custom UI; write starter prompts instead. The guidelines say screenshots "are no longer shown in the Directory"; the submission-errors page allows them only when the tool scan reports a UI output template, one per starter prompt, exactly 706 px wide and 400–860 px tall. Without custom UI, ship none and write starter prompts instead.

When something is learned

  • This skill is general and will be published. Write the rule and why it holds; a product appears only as an example, named by kind, never by its name, listing or plugin id, commits, paths or account names.
  • Date what OpenAI did or required. Use "read on" or "observed in". When it changes, correct the line; never leave the old one beside the new.
  • What is true of one product goes in that product's repository. This includes its plugin's id, package versions, review states and dates, the identity it publishes under, its verified clients.
  • A rule a test or the checker can hold gets one. Say what it asserts.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexVerifiedInstall