How to Create a New OpenAI Plugin: Complete Scaffold Guide

You create a new OpenAI plugin by running the create_basic_plugin.py scaffold script from the openai/plugins repository, which generates a standardized directory structure with a placeholder manifest and optional marketplace registration.

The openai/plugins repository provides a built-in Plugin Creator skill that automates the scaffolding of new Codex plugins. When you need to create a new OpenAI plugin, this tool generates the required folder hierarchy, populates a plugin.json manifest template, and optionally registers the plugin in your local marketplace configuration.

Core Components of the Plugin Creator

The plugin creation system relies on four primary files that define the scaffold behavior and validation schema.

• Scaffold script – Located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py, this Python script creates the folder hierarchy and placeholder plugin.json.
• Skill documentation – The .agents/skills/plugin-creator/SKILL.md file explains workflow options, naming conventions, and marketplace integration rules.
• Marketplace definition – The .agents/plugins/marketplace.json file maps plugin names to local paths and defines installation and authentication policies.
• Reference manifest – The plugins/figma/.codex-plugin/plugin.json provides a concrete example of a fully populated plugin manifest following the required schema.

Step-by-Step Guide to Create a New OpenAI Plugin

1. Run the Scaffold Script

Execute the creator script from the repository root to generate your plugin skeleton.

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

The script normalizes your <plugin-name> to lower-case hyphen-case (for example, My Plugin becomes my-plugin). By default, the scaffold creates the plugin at ~/plugins/<plugin-name> and adds a personal marketplace entry at ~/.agents/plugins/marketplace.json.

2. Add Optional Directories

Append flags to the command to create additional subdirectories for specific 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 automation scripts.
• --with-assets – Creates an assets/ directory for icons and screenshots.
• --with-mcp – Creates a stub .mcp.json file.
• --with-apps – Creates a stub .app.json file.
• --with-marketplace – Automatically adds or updates the entry in the marketplace JSON file.

3. Edit the Plugin Manifest

Open <plugin-root>/.codex-plugin/plugin.json and replace every [TODO: …] placeholder with real metadata including name, version, description, author, URLs, and the interface object describing UI capabilities.

4. Configure Marketplace Registration

If you passed --with-marketplace, the script creates a new marketplace file or appends to an existing one at the location specified by --marketplace-path. The generated entry contains:

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

Use --install-policy to override the default AVAILABLE status (options include NOT_AVAILABLE or INSTALLED_BY_DEFAULT). Use --auth-policy to change ON_INSTALL to ON_USE. Pass --force to replace an existing entry with the same name.

5. Populate Skills and Assets

Add OpenAI Skill YAML files to the skills/ directory, place UI assets like icons into assets/, and implement any custom commands or hooks in their respective folders.

Complete Scaffold Example

The following command creates a fully equipped plugin named quick-notes in a custom directory:

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

This generates the following structure:

./plugins/quick-notes/
├─ .codex-plugin/
│   └─ plugin.json          # Contains [TODO: ...] placeholders

├─ skills/                  # Ready for YAML skill definitions

├─ hooks/                   # Custom hook implementations

├─ scripts/                 # Automation scripts

├─ assets/                  # Icons and screenshots

├─ .mcp.json                # MCP configuration stub

└─ .app.json                # App configuration stub

Edit ./plugins/quick-notes/.codex-plugin/plugin.json to replace the placeholders with production values. The marketplace entry automatically references the local path for immediate testing in the Codex UI.

Summary

• Use the scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to generate a new plugin directory with proper naming conventions.
• Include optional flags like --with-skills and --with-assets to pre-create directories for complete functionality.
• Customize the manifest in .codex-plugin/plugin.json by replacing all [TODO: …] placeholders with valid metadata and interface definitions.
• Register automatically using --with-marketplace to add entries to .agents/plugins/marketplace.json with configurable installation and authentication policies.
• Reference the Figma plugin at plugins/figma/.codex-plugin/plugin.json for a complete example of a production-ready manifest.

Frequently Asked Questions

Where does the scaffold script create new plugins by default?

By default, the script creates plugins at ~/plugins/<plugin-name> and updates the personal marketplace at ~/.agents/plugins/marketplace.json. You can override these locations using the --path and --marketplace-path arguments.

Do I need to manually edit the marketplace JSON file?

No. When you pass the --with-marketplace flag, the script automatically generates the marketplace entry with the correct structure, including the source path and policy settings. You only need to manually edit the file if you need to change the category or policies after creation.

What fields must I fill in the generated plugin.json?

You must replace all [TODO: …] placeholders in the generated .codex-plugin/plugin.json with real values, including the plugin name, version, description, author information, URLs, and the interface object that defines the display name, descriptions, and capabilities for the Codex UI.

How do I test my plugin before publishing?

After filling out the manifest and adding your skills, the plugin is ready for local testing. The repository documentation indicates that you can run the plugin in a local Codex environment by ensuring the marketplace entry points to your local path, allowing the Codex UI to load and execute your plugin code directly from the filesystem.

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