# How to Create a New OpenAI Codex Plugin: Complete Developer Guide

> Learn to create a new OpenAI Codex plugin with our developer guide. Scaffold a manifest, customize metadata, add skills, and register for discovery. Get started today.

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

---

**To create a new OpenAI Codex plugin, run the plugin-creator scaffold script to generate a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, customize the metadata, add optional skills and assets, and optionally register it in a marketplace.json file for UI discovery.**

The openai/plugins repository provides official tooling to extend Codex with custom capabilities. This guide covers the complete workflow for creating a new OpenAI Codex plugin using the built-in scaffolding system and manifest specifications.

## Scaffold the Plugin Structure

The repository includes a **plugin-creator skill** that automates plugin initialization. Run the scaffold script from the repository root to create a complete plugin skeleton.

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

```

By default, this creates `~/plugins/<plugin-name>/` containing the required manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) along with starter directories for skills and assets. For detailed usage options and advanced flags, refer to the skill documentation at [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md).

## Configure the Plugin Manifest

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file defines your plugin's identity and capabilities. The scaffold generates a full-schema placeholder with `TODO` values that you must replace with actual metadata.

Key fields include `name`, `version`, `description`, `author`, and `interface` configuration. The complete schema specification is documented in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md).

Here is a minimal valid configuration:

```json
{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A demo Codex plugin",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/my-awesome-plugin",
  "repository": "https://github.com/yourname/my-awesome-plugin",
  "license": "MIT",
  "keywords": ["demo", "codex"],
  "skills": "./skills/",
  "interface": {
    "displayName": "My Awesome Plugin",
    "shortDescription": "Demo plugin for Codex",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"]
  }
}

```

## Add Skills and Assets

Populate your plugin with functionality by adding:

- **`skills/`** – One or more skill folders, each containing a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file and any supporting code
- **`assets/`** – Icons, logos, and screenshots referenced from the `interface` section of your manifest
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** or **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** – Optional custom app or MCP server definitions

These directories sit alongside the `.codex-plugin/` folder in your plugin root.

## Register in the Marketplace

To make your plugin discoverable in the Codex UI, add it to a **marketplace.json** file. Run the scaffold with the `--with-marketplace` flag to automate this:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-awesome-plugin --with-marketplace

```

**Personal plugins** are stored in `~/.agents/plugins/marketplace.json`, while **repository or team plugins** use `<repo-root>/.agents/plugins/marketplace.json`. The script generates an entry like this:

```json
{
  "name": "my-awesome-plugin",
  "source": { "source": "local", "path": "./plugins/my-awesome-plugin" },
  "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
  "category": "Productivity"
}

```

The marketplace schema is defined in the reference file [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md).

## Test and Publish

Test your plugin locally by opening the Codex app and pointing it at your plugin root (`~/plugins/my-awesome-plugin`) or at the marketplace file. Verify that the plugin appears in the UI, that its skills are discoverable, and that any API calls execute correctly.

To publish, push the plugin folder and updated [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) to a public repository. Share the plugin using the Codex deeplink format: `codex://plugins/<plugin-name>?marketplacePath=<absolute-path-to-marketplace.json>`.

## Summary

- **Scaffold** new plugins using [`.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 generate the required directory structure and manifest.
- **Configure** the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest with valid metadata following the schema in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md).
- **Extend** functionality by adding skills to the `skills/` directory and assets to the `assets/` directory.
- **Register** plugins in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) using the `--with-marketplace` flag for UI discovery.
- **Distribute** via public repositories and Codex deeplinks.

## Frequently Asked Questions

### What is the minimum required file for a Codex plugin?

Every Codex plugin requires a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file that defines the plugin's name, version, and interface metadata. While skills and assets are optional, this manifest file is mandatory for Codex to recognize and load the plugin.

### How do I share my plugin with other Codex users?

Share your plugin by publishing it to a public Git repository and distributing a Codex deeplink in the format `codex://plugins/<plugin-name>?marketplacePath=<url-or-path-to-marketplace.json>`. Recipients can use this link to install the plugin directly into their Codex environment.

### What is the difference between personal and repository-level marketplace entries?

Personal marketplace entries are stored in `~/.agents/plugins/marketplace.json` and are only available to your local Codex instance. Repository-level entries reside in `<repo-root>/.agents/plugins/marketplace.json` and can be committed to version control, making them available to team members or public users who clone the repository.

### Where can I find the complete schema specification for plugin.json?

The complete schema for both [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) is documented in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) within the openai/plugins repository. This file describes all available fields, data types, and validation requirements for plugin manifests.