How to Submit a Plugin to the OpenAI Marketplace: A Complete Developer Guide

Submitting a plugin to the OpenAI Marketplace requires creating a compliant directory structure with a manifest file, defining skills in markdown, validating locally with Codex tooling, and uploading the zipped package through the OpenAI Developer Portal.

The openai/plugins repository defines the reference architecture for building Codex-compatible plugins that extend ChatGPT functionality. To submit a plugin to the OpenAI Marketplace, you must construct a specific directory layout, define functional skills using markdown specifications, and pass validation checks before uploading your package through the official developer dashboard.

Directory Structure and Manifest Configuration

Every plugin resides under plugins/<plugin-name>/ and must include a .codex-plugin directory containing the manifest file. The repository enforces a strict hierarchy to ensure the marketplace can parse metadata and assets correctly.

Required Folder Layout

The minimal required structure follows this pattern:

plugins/
└─ <plugin-name>/
   ├─ .codex-plugin/
   │   └─ plugin.json          # Required manifest

   ├─ skills/
   │   └─ <skill-name>/
   │      └─ SKILL.md          # Skill definition

   ├─ assets/                  # Optional icons and screenshots

   └─ .app.json                # Optional front-end configuration

Configuring plugin.json

The manifest at plugins/<plugin-name>/.codex-plugin/plugin.json declares the plugin's metadata and security policies. As implemented in the Zoom plugin example at plugins/zoom/.codex-plugin/plugin.json, the file must specify the authentication policy and installation behavior.

{
  "name": "zoom",
  "displayName": "Zoom",
  "description": "Integrates Zoom meetings, webinars, and chat into ChatGPT.",
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Communication"
}

Defining Functional Skills

Skills represent the functional units of your plugin, defined as markdown files containing SKILL blocks that specify triggers and agent configurations. Each skill maps user intents to specific API interactions.

Skill Markdown Structure

Place skill definitions in plugins/<plugin-name>/skills/<skill-name>/SKILL.md. The Zoom Team Chat implementation at plugins/zoom/skills/team-chat/SKILL.md demonstrates the required format:

# Zoom Team Chat

description: "Enable ChatGPT to post messages, create meetings, and handle form submissions in Zoom Team Chat."

# Triggers

- on: add, create, implement, help me, chat, button click, form submission

Optional Agent Configuration

You may include additional agent YAML files alongside the SKILL.md to define how the skill communicates with external APIs, though the markdown file remains the primary interface definition.

Local Validation and Testing

Before submitting to the marketplace, validate your plugin using the Codex CLI tools included in the openai/plugins repository. Local testing catches manifest errors, missing scopes, and broken skill definitions prior to review. For detailed workflow documentation, refer to plugins/openai-developers/skills/build-chatgpt-app/references/apps-sdk-docs-workflow.md.

Running Local Validation

Execute the following commands from the repository root to start a local server and run tests:

# Start the plugin locally

codex run plugins/zoom

# Execute the built-in test suite

codex test plugins/zoom

Generating Submission Metadata

The repository includes a helper skill at plugins/openai-developers/skills/chatgpt-app-submission/SKILL.md that generates the required chatgpt-app-submission.json file. Run this skill to create the metadata required by the OpenAI submission form:

codex run plugins/openai-developers/skills/chatgpt-app-submission

# Output: chatgpt-app-submission.json in your working directory

Packaging and Submitting to the Marketplace

Once validation passes, package your plugin as a ZIP archive and submit it through the OpenAI Developer Portal. The marketplace ingestion process requires the complete plugin directory including hidden folders like .codex-plugin.

Creating the Distribution Archive

Zip the entire plugin directory from within the plugins folder:

cd plugins
zip -r zoom.zip zoom

The resulting archive must contain the .codex-plugin directory, all skill definitions, and any assets required for the marketplace listing.

Uploading via the Developer Portal

Submit your plugin through the OpenAI Developer Dashboard:

1. Navigate to Marketplace → Submit a Plugin.
2. Upload the .zip file containing your plugin directory.
3. Complete the submission form using metadata from plugin.json:
   • Display name and Description: Auto-populated from the manifest
   • Category: Must match marketplace categories (e.g., Communication)
   • Authentication: Set to ON_INSTALL per your policy.authentication field
   • Privacy policy URL: Publicly accessible data handling documentation
   • Assets: Upload icons and screenshots from your assets/ folder
   • chatgpt-app-submission.json: Paste the JSON generated by the helper skill
4. Click Submit for Review to begin the security and compliance evaluation.

Post-Submission Review Process

After submission, the OpenAI review team evaluates your plugin for security vulnerabilities, policy compliance, and functional correctness. Monitor the Developer Dashboard for review comments and address any requested changes promptly by modifying plugin.json or skill files and re-uploading the archive. Once approved, the plugin becomes visible in the marketplace catalog defined at .agents/plugins/marketplace.json and available for end-user installation.

Summary

• Directory structure: Create plugins/<name>/ with .codex-plugin/plugin.json, skills/, and optional assets/
• Manifest requirements: Define name, displayName, description, and policy fields in the JSON manifest
• Skill definitions: Write markdown files with SKILL blocks under skills/<name>/SKILL.md
• Local validation: Use codex run and codex test to verify functionality before submission
• Submission preparation: Generate chatgpt-app-submission.json using the helper skill and package the directory as a ZIP file
• Marketplace upload: Submit through the OpenAI Developer Portal and complete the review process

Frequently Asked Questions

What authentication policies does the OpenAI Marketplace support?

The marketplace supports authentication policies defined in the policy.authentication field of plugin.json. The Zoom plugin example uses "ON_INSTALL", which requires users to authenticate when first installing the plugin. Other policies may include "NONE" for public data or OAuth flows, depending on the sensitivity of the data accessed.

Can I submit a plugin without the chatgpt-app-submission.json file?

While the core plugin submission requires only the ZIP archive containing plugin.json and skill definitions, including chatgpt-app-submission.json streamlines the process for ChatGPT App submissions. Generate this file using the helper skill at plugins/openai-developers/skills/chatgpt-app-submission/SKILL.md to ensure all required metadata fields are properly formatted.

How long does the OpenAI Marketplace review process take?

The review timeline varies based on plugin complexity and security requirements. The OpenAI team evaluates submissions for security vulnerabilities, API compliance, and functional correctness. You will receive status updates via email, with any required changes appearing in the Developer Dashboard under your submission details.

Where is the official marketplace catalog defined?

The curated list of available plugins resides in .agents/plugins/marketplace.json within the openai/plugins repository. This file indexes all approved plugins that appear in the marketplace, including their metadata and category assignments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}