# How to Create a New OpenAI Plugin: Complete Scaffold Guide

> Learn how to create a new OpenAI plugin using the official scaffold script. Get a complete guide to generating your plugin structure and marketplace registration quickly.

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

---

**You create a new OpenAI plugin by running the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py), this Python script creates the folder hierarchy and placeholder [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json).
- **Skill documentation** – The [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) file explains workflow options, naming conventions, and marketplace integration rules.
- **Marketplace definition** – The [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.

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

```json
{
  "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:

```bash
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`](https://github.com/openai/plugins/blob/main/./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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) with configurable installation and authentication policies.
- **Reference the Figma plugin** at [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.