# How to Create a New Codex Plugin in the OpenAI Plugins Repository

> Create a new Codex plugin using the OpenAI Plugins repository's scaffold script. Generate your manifest and asset directories quickly and start building.

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

---

**You can create a new Codex plugin using the Plugin-Creator skill's 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), which generates the mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest and optional asset directories under `plugins/<plugin-name>/`.**

The OpenAI Plugins repository provides a standardized framework for building Codex plugins that extend AI capabilities. Each plugin lives in its own directory under `plugins/` and requires a JSON manifest to define its metadata and capabilities. This guide walks you through the exact steps to **create a new Codex plugin** using the built-in scaffolding tools and explains the required directory structure and configuration files.

## Plugin Architecture and Directory Structure

Every Codex plugin follows a strict directory layout. The repository stores each plugin in its own folder under `plugins/<plugin-name>/` according to the repository overview in [`README.md`](https://github.com/openai/plugins/blob/main/README.md).

A valid plugin must contain:

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – The mandatory manifest file following the Codex Plugin JSON schema
- **`skills/`** – Optional directory for custom skill definitions
- **`assets/`** – Optional directory for icons, logos, and screenshots
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** – Optional configuration for application-specific settings
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** – Optional Model Context Protocol configuration

The scaffold script enforces these conventions and creates the hierarchy automatically.

## Using the Plugin-Creator Skill

The repository includes a **Plugin-Creator skill** that wraps a Python scaffold script. The core 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 is available in [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md).

The script performs several validation and normalization steps:

- Converts plugin names to lowercase-hyphen-case
- Enforces a 64-character limit on plugin names
- Creates the folder hierarchy
- Writes a placeholder [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) with `[TODO: …]` markers
- Optionally updates the marketplace JSON file

## Step-by-Step: Scaffolding a New Plugin

### Create a Simple Personal Plugin

For a basic personal plugin outside the repository:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin

```

This creates:

```

~/plugins/my-plugin/
└── .codex-plugin/
    └── plugin.json

```

### Create a Repository Plugin with Full Assets

For a production-ready plugin within the repository, including marketplace integration:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    my-awesome-plugin \
    --path ./plugins \
    --with-skills --with-assets --with-marketplace \
    --marketplace-path ./.agents/plugins/marketplace.json

```

This generates:

```text
plugins/my-awesome-plugin/
├── .codex-plugin/
│   └── plugin.json          # Placeholder manifest

├── assets/                  # Empty directory for icons/screenshots

└── skills/                  # Empty directory for skill definitions

```

The script also appends an entry to [`./.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/./.agents/plugins/marketplace.json) with default policies (`installation: "AVAILABLE"`, `authentication: "ON_INSTALL"`) and category `"Productivity"`.

## Customizing the Plugin Manifest

The generated [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) contains placeholder values that you must replace before publishing. Here is the structure created by the scaffold script:

```json
{
  "name": "my-awesome-plugin",
  "version": "[TODO: 1.2.0]",
  "description": "[TODO: Brief plugin description]",
  "author": {
    "name": "[TODO: Author Name]",
    "email": "[TODO: author@example.com]",
    "url": "[TODO: https://github.com/author]"
  },
  "interface": {
    "displayName": "[TODO: Plugin Display Name]",
    "shortDescription": "[TODO: Short description for subtitle]",
    "category": "[TODO: Productivity]",
    "capabilities": ["[TODO: Interactive]", "[TODO: Write]"],
    "brandColor": "[TODO: #3B82F6]",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png"
  }
}

```

For a complete reference, inspect the example manifest at [`plugins/apollo/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/apollo/.codex-plugin/plugin.json), which demonstrates fully-populated fields for a production plugin.

## Marketplace Integration

The scaffold script handles marketplace registration through the `update_marketplace_json` function (lines 29-65 in the source file). It supports two deployment targets:

- **Personal plugins**: Stored in `~/.agents/plugins/marketplace.json`
- **Repository plugins**: Stored in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) relative to the repository root

Each marketplace entry includes:

- `source.path` – Relative path to the plugin directory
- `installation` – Policy set to `"AVAILABLE"` by default
- `authentication` – Set to `"ON_INSTALL"` by default
- `category` – Defaults to `"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 directory structure and manifest.
- Every plugin must include a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest following the Codex Plugin JSON schema.
- The script normalizes plugin names to lowercase-hyphen-case with a 64-character limit.
- Optional directories like `skills/` and `assets/` can be added with `--with-skills` and `--with-assets` flags.
- Marketplace entries are automatically generated for personal or repository-wide distribution via the `update_marketplace_json` function.

## Frequently Asked Questions

### Where is the scaffold script located in the OpenAI Plugins repository?

The scaffold script is 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 is wrapped by the Plugin-Creator skill, which is documented in [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md).

### What files are required to create a new Codex plugin?

Every plugin requires a manifest file at `plugins/<plugin-name>/.codex-plugin/plugin.json`. Optional files include the `skills/` directory for custom capabilities, `assets/` for icons and images, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for application settings, and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) for Model Context Protocol configurations.

### How does the scaffold script validate plugin names?

The script enforces a 64-character limit and normalizes the name to lowercase-hyphen-case. For example, "My Awesome Plugin" becomes "my-awesome-plugin" in the directory structure.

### What is the difference between personal and repository-wide marketplace entries?

Personal plugins update `~/.agents/plugins/marketplace.json` in your home directory, while repository-wide plugins use `<repo>/.agents/plugins/marketplace.json`. Both contain installation policies, authentication settings, and category metadata, but repo-wide entries are versioned with the repository for team sharing.