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

> Learn how to contribute to OpenAI Codex plugins. Fork the repo, create a plugin directory, use scaffolding, and submit a pull request. Start building new integrations today.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-01

---

**To contribute to the OpenAI Codex plugins, fork the repository, create a new plugin directory with a valid [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), optionally use the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) scaffolding script, and submit a pull request for review.**

The [openai/plugins](https://github.com/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) [plugins/finn/.codex-plugin/plugin.json](https://github.com/openai/plugins/blob/main/plugins/finn/.codex-plugin/plugin.json#L1-L32). The root [README.md](https://github.com/openai/plugins/blob/main/README.md#L1-L9) outlines the high-level structure, while [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) automatically indexes all valid plugins without manual registration [marketplace.json](https://github.com/openai/plugins/blob/main/.agents/plugins/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:

```bash
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:

```bash
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`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/.codex-plugin/plugin.json) with required fields, placeholder assets, and an empty `skills/` directory [create_basic_plugin.py](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py).

### 3. Configure the Plugin Manifest

Edit the generated [`plugin.json`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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](https://github.com/openai/plugins/blob/main/plugins/finn/.codex-plugin/plugin.json#L1-L32).

### 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`](https://github.com/openai/plugins/blob/main/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:

```bash
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](https://github.com/openai/plugins/blob/main/README.md#L1-L9)**: Repository overview and contribution guidelines.
- **[.agents/plugins/marketplace.json](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)**: Auto-discovery registry that indexes all plugins under `plugins/`.
- **[.agents/skills/plugin-creator/scripts/create_basic_plugin.py](https://github.com/openai/plugins/blob/main/.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](https://github.com/openai/plugins/blob/main/plugins/finn/.codex-plugin/plugin.json#L1-L32).
- **`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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest.
- **Use the scaffolding script** at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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](https://github.com/openai/plugins/blob/main/plugins/finn/.codex-plugin/plugin.json#L1-L32).

### How does the marketplace discover newly added plugins?

The repository uses [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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](https://github.com/openai/plugins/blob/main/.agents/plugins/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py).