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

> Learn how to create a new OpenAI plugin using the official scaffold script. Generate your plugin structure and edit the manifest file with this comprehensive guide.

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

---

**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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) generates the folder hierarchy and placeholder manifest.
- **Plugin Manifest** – [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) defines metadata, UI interface, and capabilities.
- **Marketplace Registry** – [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) maps plugin names to local paths and installation policies.
- **Example Reference** – [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/.mcp.json) for Model Context Protocol configuration.
- `--with-apps` – Generates a stub [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for app-specific settings.
- `--with-marketplace` – Automatically adds an entry to the marketplace JSON file.

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

```

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

```json
{
  "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`](https://github.com/openai/plugins/blob/main/README.md) and the specific plugin documentation before distribution.

## Minimal Working Example

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

```bash
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`:

```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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) to generate the required [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). Use the `--with-marketplace` flag when running [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) by default. Optional directories like `skills/`, `assets/`, `hooks/`, and configuration files ([`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md). The marketplace schema and example entries are located in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json).