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

> Learn to create an OpenAI plugin easily with our guide. Use the scaffold script to build your plugin's structure and manifest file. Get started today!

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-26

---

**You can create an OpenAI plugin by running the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) generates the folder hierarchy and placeholder manifest
- **Skill documentation** – [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) explains naming rules and workflow options
- **Marketplace registry** – [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) maps plugin names to local paths and defines installation policies
- **Reference manifest** – [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`).

```bash
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`](https://github.com/openai/plugins/blob/main/.mcp.json) configuration
- `--with-apps` – Creates a stub [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) configuration
- `--with-marketplace` – Automatically registers the plugin in the marketplace JSON file

For a complete scaffold with all options:

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/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":

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

```

This generates the following structure:

```text
~/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.