How to Create an OpenAI Plugin: A Complete Guide to the Codex Plugin Creator

You can create an OpenAI plugin by running the create_basic_plugin.py scaffold script, which generates a directory structure with a manifest file and optional marketplace entry.

OpenAI plugins extend the capabilities of the Codex AI agent by adding custom skills, hooks, and assets. According to the openai/plugins repository, the recommended way to create an OpenAI plugin is using the Plugin Creator skill, which handles the boilerplate structure and marketplace registration automatically.

Understanding the OpenAI Plugin Architecture

Before creating a plugin, you need to understand the core components defined in the source code. An OpenAI plugin consists of a manifest file (.codex-plugin/plugin.json) and optional companion assets managed through a centralized marketplace registry.

The repository provides four key files that define the creation workflow:

• Scaffold script – .agents/skills/plugin-creator/scripts/create_basic_plugin.py generates the folder hierarchy and placeholder manifest
• Skill documentation – .agents/skills/plugin-creator/SKILL.md explains naming rules and workflow options
• Marketplace registry – .agents/plugins/marketplace.json maps plugin names to local paths and defines installation policies
• Reference manifest – plugins/figma/.codex-plugin/plugin.json shows the required schema for a production-ready plugin

Step-by-Step Guide to Create an OpenAI Plugin

Run the Scaffold Script

Start by executing the creation script from the repository root. The script normalizes your plugin name to lower-case hyphen-case (e.g., My Plugin becomes my-plugin).

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

By default, this creates the plugin under ~/plugins/<plugin-name> and adds a personal marketplace entry at ~/.agents/plugins/marketplace.json.

Add Optional Directories and Components

Append flags to the scaffold command to create specific subdirectories for your plugin's functionality:

• --with-skills – Creates a skills/ directory for skill definitions
• --with-hooks – Creates a hooks/ directory for custom hooks
• --with-scripts – Creates a scripts/ directory for utility scripts
• --with-assets – Creates an assets/ directory for icons and screenshots
• --with-mcp – Creates a stub .mcp.json configuration
• --with-apps – Creates a stub .app.json configuration
• --with-marketplace – Automatically registers the plugin in the marketplace JSON file

For a complete scaffold with all options:

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

Edit the Plugin Manifest

Open the generated .codex-plugin/plugin.json file and replace all [TODO: …] placeholders with real metadata. The manifest must include an interface object describing the UI display name, descriptions, capabilities, and branding.

The manifest follows the same schema as existing plugins like the Figma plugin located at plugins/figma/.codex-plugin/plugin.json.

Update the Marketplace Configuration

If you used --with-marketplace, the script creates or appends an entry to the marketplace file. Each entry contains the plugin name, source path, installation policy, and authentication policy:

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

Override defaults using --install-policy (options: AVAILABLE, NOT_AVAILABLE, INSTALLED_BY_DEFAULT) and --auth-policy (options: ON_INSTALL, ON_USE). Use --force to replace existing entries.

Add Skills and Assets

Populate the skills/ directory with OpenAI Skill YAML files defining your custom commands. Add UI assets like icons and screenshots to the assets/ directory. Implement any custom logic in the hooks/ or scripts/ directories as needed.

Test and Publish

Test your plugin locally using the Codex environment according to the repository's README.md. Once verified, publish by submitting a pull request to the openai/plugins repository or distributing the plugin folder to your team's marketplace file.

Example: Creating a Minimal OpenAI Plugin

Here is a complete example creating a plugin called "quick-notes":

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py quick-notes \
    --with-skills --with-assets --with-marketplace

This generates the following structure:

~/plugins/quick-notes/
├─ .codex-plugin/
│   └─ plugin.json          # placeholder manifest

├─ skills/                  # ready for skill definitions

├─ assets/
│   └─ icon.png             # add your icon here

└─ .app.json                # optional app placeholder

Edit ~/plugins/quick-notes/.codex-plugin/plugin.json to replace placeholder values. The marketplace entry is automatically added to ~/.agents/plugins/marketplace.json with the following structure:

{
  "name": "quick-notes",
  "source": { "source": "local", "path": "./plugins/quick-notes" },
  "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
  "category": "Productivity"
}

Summary

• Use .agents/skills/plugin-creator/scripts/create_basic_plugin.py to scaffold a new OpenAI plugin with normalized naming
• Add optional directories using flags like --with-skills, --with-hooks, and --with-assets to match your plugin's requirements
• Edit .codex-plugin/plugin.json to replace [TODO: …] placeholders with real metadata and interface definitions
• Register your plugin in the marketplace using --with-marketplace and configure installation policies with --install-policy and --auth-policy
• Test locally before publishing via pull request to the openai/plugins repository

Frequently Asked Questions

What file defines an OpenAI plugin's identity?

The plugin identity is defined in .codex-plugin/plugin.json, which contains the manifest metadata including the interface object for UI display, version information, and capability declarations. This file follows the schema demonstrated in plugins/figma/.codex-plugin/plugin.json.

How do I register my plugin so Codex can discover it?

Register your plugin by including the --with-marketplace flag when running the scaffold script. This adds an entry to .agents/plugins/marketplace.json mapping the plugin name to its local path and defining installation policies such as AVAILABLE or INSTALLED_BY_DEFAULT.

Can I customize the installation and authentication behavior?

Yes. Use --install-policy to set whether the plugin is AVAILABLE, NOT_AVAILABLE, or INSTALLED_BY_DEFAULT. Use --auth-policy to specify whether authentication occurs ON_INSTALL or ON_USE. You can also use --force to overwrite existing marketplace entries during development.

Where should I place skill definitions and UI assets?

Place OpenAI Skill YAML files in the skills/ directory and UI assets like icons in the assets/ directory. These directories are created when you include --with-skills and --with-assets flags during the scaffold process.

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