How to Create a New Codex Plugin in the OpenAI Plugins Repository

You can create a new Codex plugin using the Plugin-Creator skill's scaffold script located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py, which generates the mandatory .codex-plugin/plugin.json manifest and optional asset directories under plugins/<plugin-name>/.

The OpenAI Plugins repository provides a standardized framework for building Codex plugins that extend AI capabilities. Each plugin lives in its own directory under plugins/ and requires a JSON manifest to define its metadata and capabilities. This guide walks you through the exact steps to create a new Codex plugin using the built-in scaffolding tools and explains the required directory structure and configuration files.

Plugin Architecture and Directory Structure

Every Codex plugin follows a strict directory layout. The repository stores each plugin in its own folder under plugins/<plugin-name>/ according to the repository overview in README.md.

A valid plugin must contain:

• .codex-plugin/plugin.json – The mandatory manifest file following the Codex Plugin JSON schema
• skills/ – Optional directory for custom skill definitions
• assets/ – Optional directory for icons, logos, and screenshots
• .app.json – Optional configuration for application-specific settings
• .mcp.json – Optional Model Context Protocol configuration

The scaffold script enforces these conventions and creates the hierarchy automatically.

Using the Plugin-Creator Skill

The repository includes a Plugin-Creator skill that wraps a Python scaffold script. The core logic resides in .agents/skills/plugin-creator/scripts/create_basic_plugin.py, while human-readable documentation is available in .agents/skills/plugin-creator/SKILL.md.

The script performs several validation and normalization steps:

• Converts plugin names to lowercase-hyphen-case
• Enforces a 64-character limit on plugin names
• Creates the folder hierarchy
• Writes a placeholder plugin.json with [TODO: …] markers
• Optionally updates the marketplace JSON file

Step-by-Step: Scaffolding a New Plugin

Create a Simple Personal Plugin

For a basic personal plugin outside the repository:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin

This creates:

~/plugins/my-plugin/
└── .codex-plugin/
    └── plugin.json

Create a Repository Plugin with Full Assets

For a production-ready plugin within the repository, including marketplace integration:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    my-awesome-plugin \
    --path ./plugins \
    --with-skills --with-assets --with-marketplace \
    --marketplace-path ./.agents/plugins/marketplace.json

This generates:

plugins/my-awesome-plugin/
├── .codex-plugin/
│   └── plugin.json          # Placeholder manifest

├── assets/                  # Empty directory for icons/screenshots

└── skills/                  # Empty directory for skill definitions

The script also appends an entry to ./.agents/plugins/marketplace.json with default policies (installation: "AVAILABLE", authentication: "ON_INSTALL") and category "Productivity".

Customizing the Plugin Manifest

The generated plugin.json contains placeholder values that you must replace before publishing. Here is the structure created by the scaffold script:

{
  "name": "my-awesome-plugin",
  "version": "[TODO: 1.2.0]",
  "description": "[TODO: Brief plugin description]",
  "author": {
    "name": "[TODO: Author Name]",
    "email": "[TODO: author@example.com]",
    "url": "[TODO: https://github.com/author]"
  },
  "interface": {
    "displayName": "[TODO: Plugin Display Name]",
    "shortDescription": "[TODO: Short description for subtitle]",
    "category": "[TODO: Productivity]",
    "capabilities": ["[TODO: Interactive]", "[TODO: Write]"],
    "brandColor": "[TODO: #3B82F6]",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png"
  }
}

For a complete reference, inspect the example manifest at plugins/apollo/.codex-plugin/plugin.json, which demonstrates fully-populated fields for a production plugin.

Marketplace Integration

The scaffold script handles marketplace registration through the update_marketplace_json function (lines 29-65 in the source file). It supports two deployment targets:

• Personal plugins: Stored in ~/.agents/plugins/marketplace.json
• Repository plugins: Stored in .agents/plugins/marketplace.json relative to the repository root

Each marketplace entry includes:

• source.path – Relative path to the plugin directory
• installation – Policy set to "AVAILABLE" by default
• authentication – Set to "ON_INSTALL" by default
• category – Defaults to "Productivity"

Summary

• Use the scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to generate the required directory structure and manifest.
• Every plugin must include a .codex-plugin/plugin.json manifest following the Codex Plugin JSON schema.
• The script normalizes plugin names to lowercase-hyphen-case with a 64-character limit.
• Optional directories like skills/ and assets/ can be added with --with-skills and --with-assets flags.
• Marketplace entries are automatically generated for personal or repository-wide distribution via the update_marketplace_json function.

Frequently Asked Questions

Where is the scaffold script located in the OpenAI Plugins repository?

The scaffold script is located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py. This Python script is wrapped by the Plugin-Creator skill, which is documented in .agents/skills/plugin-creator/SKILL.md.

What files are required to create a new Codex plugin?

Every plugin requires a manifest file at plugins/<plugin-name>/.codex-plugin/plugin.json. Optional files include the skills/ directory for custom capabilities, assets/ for icons and images, .app.json for application settings, and .mcp.json for Model Context Protocol configurations.

How does the scaffold script validate plugin names?

The script enforces a 64-character limit and normalizes the name to lowercase-hyphen-case. For example, "My Awesome Plugin" becomes "my-awesome-plugin" in the directory structure.

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

Personal plugins update ~/.agents/plugins/marketplace.json in your home directory, while repository-wide plugins use <repo>/.agents/plugins/marketplace.json. Both contain installation policies, authentication settings, and category metadata, but repo-wide entries are versioned with the repository for team sharing.

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