How to Contribute to OpenAI Codex Plugins: A Complete Developer Guide

To contribute to the OpenAI Codex plugins, fork the repository, create a new plugin directory with a valid plugin.json manifest at .codex-plugin/plugin.json, optionally use the create_basic_plugin.py scaffolding script, and submit a pull request for review.

The openai/plugins repository serves as the official registry for Codex-compatible extensions. Contributing requires understanding the manifest-driven architecture where each plugin defines its metadata, assets, and behavior through a standardized JSON configuration.

Understanding the Repository Architecture

The repository follows a strict directory convention. Each plugin resides in plugins/<plugin-name>/ and must include a manifest at .codex-plugin/plugin.json plugins/finn/.codex-plugin/plugin.json. The root README.md outlines the high-level structure, while .agents/plugins/marketplace.json automatically indexes all valid plugins without manual registration marketplace.json.

Step-by-Step Contribution Workflow

1. Fork and Clone the Repository

Start by forking the repository on GitHub and cloning your local copy:

git clone https://github.com/YOUR_USERNAME/plugins.git
cd plugins

2. Scaffold Your Plugin Directory

Use the built-in scaffolding script to generate a compliant skeleton:

python .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    --name my-plugin \
    --author "Your Name" \
    --description "Brief description of functionality"

This creates plugins/my-plugin/.codex-plugin/plugin.json with required fields, placeholder assets, and an empty skills/ directory create_basic_plugin.py.

3. Configure the Plugin Manifest

Edit the generated plugin.json to define your plugin's interface. Required fields include name, version, description, author, repository, license, and an interface object specifying displayName, category, and asset paths:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "One-sentence summary of capabilities.",
  "author": { "name": "Your Name", "url": "https://example.com" },
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Brief tagline",
    "category": "Productivity",
    "composerIcon": "./assets/logo.png",
    "logo": "./assets/logo.png",
    "logoDark": "./assets/logo-dark.png"
  }
}

Reference the FINN plugin for a complete production example plugins/finn/.codex-plugin/plugin.json.

4. Add Assets and Optional Skills

Place visual assets in plugins/<name>/assets/:

• logo.png for light mode
• logo-dark.png for dark mode

Optional skill scripts implementing plugin logic belong in plugins/<name>/skills/.

5. Validate and Submit

The marketplace.json file automatically discovers your plugin when placed in the plugins/ directory. Verify your manifest syntax and ensure all referenced paths resolve correctly before committing:

git add plugins/my-plugin
git commit -m "Add my-plugin to registry"
git push origin main

Open a pull request against the main repository with a clear description of the plugin's functionality.

Key Files and Their Purpose

• README.md: Repository overview and contribution guidelines.
• .agents/plugins/marketplace.json: Auto-discovery registry that indexes all plugins under plugins/.
• .agents/skills/plugin-creator/scripts/create_basic_plugin.py: Scaffolding utility for generating compliant plugin structures.
• plugins/<name>/.codex-plugin/plugin.json: Core manifest defining metadata, UI configuration, and entry points plugins/finn/.codex-plugin/plugin.json.
• plugins/<name>/.app.json: Optional UI configuration referenced by the apps field in the manifest.

Summary

• Fork and clone the openai/plugins repository to your GitHub account.
• Create a plugin directory under plugins/<name>/ with a valid .codex-plugin/plugin.json manifest.
• Use the scaffolding script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to ensure compliance with the required schema.
• Include required assets such as logo.png and logo-dark.png in the assets/ subdirectory.
• Submit a pull request after verifying the plugin appears correctly in the marketplace discovery system.

Frequently Asked Questions

What is the minimum required structure for a new Codex plugin?

Every plugin requires a directory under plugins/<name>/ containing a .codex-plugin/plugin.json manifest with fields for name, version, description, author, repository, license, and an interface object. Optional assets and skill scripts enhance functionality but are not strictly required for validation plugins/finn/.codex-plugin/plugin.json.

How does the marketplace discover newly added plugins?

The repository uses .agents/plugins/marketplace.json to automatically index all subdirectories under plugins/. You do not need to manually edit this file when adding a new plugin; the discovery system scans the directory structure programmatically marketplace.json.

Can I contribute improvements to existing plugins instead of creating new ones?

Yes. Fork the repository, modify the existing plugin's files under plugins/<existing-name>/, and submit a pull request detailing your changes. Ensure any modifications to the plugin.json manifest maintain backward compatibility or clearly document breaking changes.

What validation does the create_basic_plugin.py script perform?

The script generates a skeleton directory structure with a syntactically valid plugin.json containing all required fields, placeholder asset references, and an empty skills/ directory. It ensures the manifest schema matches the expected format used by the Codex platform, though you must still customize the content and verify asset paths manually create_basic_plugin.py.

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