How to Create a New OpenAI Plugin: Complete Scaffold and Manifest Guide

To create a new OpenAI plugin, run the Plugin Creator scaffold script python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name> to generate the directory structure, then edit <plugin-root>/.codex-plugin/plugin.json to replace the TODO placeholders with your metadata.

The openai/plugins repository provides a standardized framework for building Codex extensions through a plugin manifest system. Creating a new OpenAI plugin involves generating a scaffold directory, configuring a JSON manifest, and optionally registering the plugin in a local marketplace file. The repository includes a dedicated Plugin Creator skill that automates the boilerplate setup while enforcing the schema used by production plugins like the Figma integration.

Core Components of the Plugin System

Every OpenAI plugin consists of four primary components defined in the source code:

• Scaffold Script – .agents/skills/plugin-creator/scripts/create_basic_plugin.py generates the folder hierarchy and placeholder manifest.
• Plugin Manifest – .codex-plugin/plugin.json defines metadata, UI interface, and capabilities.
• Marketplace Registry – .agents/plugins/marketplace.json maps plugin names to local paths and installation policies.
• Example Reference – plugins/figma/.codex-plugin/plugin.json demonstrates a fully populated production manifest.

Step 1: Scaffold the Plugin Directory

Run the scaffold script from the repository root to create a new plugin skeleton:

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

The script normalizes the provided name to lower-case hyphen-case (e.g., My Plugin becomes my-plugin). By default, it creates the plugin at ~/plugins/<plugin-name> and updates the personal marketplace registry at ~/.agents/plugins/marketplace.json.

Step 2: Add Optional Directories and Stubs

Append flags to the scaffold command to create additional directories and configuration files:

• --with-skills – Creates a skills/ directory for YAML skill definitions.
• --with-hooks – Creates a hooks/ directory for lifecycle hooks.
• --with-scripts – Creates a scripts/ directory for utility scripts.
• --with-assets – Creates an assets/ directory for icons and screenshots.
• --with-mcp – Generates a stub .mcp.json for Model Context Protocol configuration.
• --with-apps – Generates a stub .app.json for app-specific settings.
• --with-marketplace – Automatically adds an entry to the marketplace JSON file.

Full example 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

Step 3: Edit the Plugin Manifest

Open <plugin-root>/.codex-plugin/plugin.json and replace every [TODO: …] placeholder with real values:

• name, version, description, author – Core metadata fields.
• interface – Object defining the UI display name, short and long descriptions, capabilities, and branding assets.

The manifest must follow the same schema used by existing plugins in the repository, as documented in .agents/skills/plugin-creator/SKILL.md.

Step 4: Configure the Marketplace Entry

If you used --with-marketplace, the script creates or appends an entry to the marketplace file. The entry structure follows this pattern:

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

Installation policies include AVAILABLE, NOT_AVAILABLE, or INSTALLED_BY_DEFAULT. Authentication policies are ON_INSTALL or ON_USE. Override defaults using --install-policy and --auth-policy, or use --force to replace an existing entry with the same name.

Step 5: Add Skills and Assets

Populate the generated directories:

1. Add OpenAI Skill YAML files to the skills/ directory.
2. Place UI assets (icons at 512x512px, screenshots) into assets/.
3. Implement custom commands or hooks in the hooks/ directory if generated.

Test the plugin locally according to the guidelines in the repository's README.md and the specific plugin documentation before distribution.

Minimal Working Example

Create a simple "quick-notes" plugin with skills and assets:

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

Resulting structure:

~/plugins/quick-notes/
├── .codex-plugin/
│   └── plugin.json          # Edit this file to replace TODOs

├── skills/                  # Add your .yaml skill definitions here

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

└── .app.json                # Optional app configuration

The marketplace entry automatically appears in ~/.agents/plugins/marketplace.json:

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

Summary

• Use the scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to generate the required .codex-plugin/plugin.json manifest and directory structure.
• Normalize plugin names to lower-case hyphen-case automatically by the scaffold tool.
• Configure optional components using flags like --with-skills, --with-assets, and --with-mcp to match your plugin's requirements.
• Edit the manifest to replace [TODO: …] placeholders with real metadata and interface definitions.
• Register in the marketplace using --with-marketplace to make the plugin discoverable by the Codex UI, specifying installation and authentication policies.

Frequently Asked Questions

What file defines the UI and capabilities of an OpenAI plugin?

The .codex-plugin/plugin.json file defines the plugin's interface, including display name, descriptions, capabilities, and branding. This manifest must be edited to replace scaffold-generated [TODO: …] placeholders with production values, as shown in the reference implementation at plugins/figma/.codex-plugin/plugin.json.

How do I make my plugin visible in the Codex UI?

You must register the plugin in a marketplace JSON file, typically .agents/plugins/marketplace.json. Use the --with-marketplace flag when running create_basic_plugin.py to automatically generate the entry with installation: "AVAILABLE", or manually add an entry containing the name, source path, policy, and category.

Can I create a plugin without skills or assets?

Yes. The scaffold script creates only the essential .codex-plugin/plugin.json by default. Optional directories like skills/, assets/, hooks/, and configuration files (.mcp.json, .app.json) are generated only when you append their corresponding flags (e.g., --with-skills, --with-assets) to the creation command.

Where is the plugin creation logic implemented in the repository?

The main scaffold logic resides in .agents/skills/plugin-creator/scripts/create_basic_plugin.py, while human-readable documentation and naming conventions are defined in .agents/skills/plugin-creator/SKILL.md. The marketplace schema and example entries are located in .agents/plugins/marketplace.json.

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