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

To create a new OpenAI Codex plugin, run the plugin-creator scaffold script to generate a .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.

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 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.

Configure the Plugin Manifest

The 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.

Here is a minimal valid configuration:

{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A demo Codex plugin",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "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 file and any supporting code
• assets/ – Icons, logos, and screenshots referenced from the interface section of your manifest
• .app.json or .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:

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:

{
  "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.

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 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 to generate the required directory structure and manifest.
• Configure the .codex-plugin/plugin.json manifest with valid metadata following the schema in .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 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 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 and marketplace.json is documented in .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.

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