# How to Structure a Custom Codex Plugin: Complete Setup Guide

> Quickly structure your own custom Codex plugin using the create_basic_plugin.py scaffold script. Get a complete setup with plugin.json manifest and marketplace registration.

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

---

**Use the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) scaffold script from the openai/plugins repository to generate a complete Codex plugin directory with a standardized [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest, optional component folders, and automatic marketplace registration.**

The openai/plugins repository ships with a dedicated plugin-creator skill that eliminates manual configuration when building Codex extensions. This automated scaffolding tool generates the required directory structure, populates a valid manifest file at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), and can register your plugin in the marketplace, providing a production-ready foundation for custom Codex integrations.

## Scaffolding Your Plugin Structure

The fastest way to structure a custom Codex plugin is using the provided 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 handles directory creation, manifest generation, and optional component setup through command-line flags.

### Running the Create Script

To generate a basic plugin skeleton, run the script with your desired plugin name:

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

```

This creates a directory at `~/plugins/my-plugin/` (or your specified parent directory) containing the mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file. The script uses the `normalize_plugin_name` helper function to convert your input to lower-case kebab-case format automatically.

### Naming Validation and Normalization

The scaffold tool enforces strict naming conventions through two internal functions defined in the create script:

- **`normalize_plugin_name`**: Converts input to lower-case kebab-case (e.g., `MyPlugin` becomes `my-plugin`)
- **`validate_plugin_name`**: Enforces a maximum length of 64 characters and validates character constraints

These validations ensure your plugin identifier remains compatible with the Codex marketplace and file system requirements.

## Configuring the Plugin Manifest

Every Codex plugin requires a manifest file that defines metadata and UI presentation logic. The scaffold script generates this automatically, but understanding its structure is essential for customization.

### The plugin.json Schema

The generated manifest lives at `<plugin-root>/.codex-plugin/plugin.json` and follows the JSON schema documented in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md). The manifest includes:

- **Top-level metadata**: `name`, `version`, `author`, and `description`
- **Interface block**: Controls how the plugin appears and behaves within the Codex app interface
- **Entry points**: References to skills, hooks, or other executable components

### Interface Configuration

The `interface` object in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) drives the UI presentation inside Codex. This block determines display names, icons, and interaction patterns. When registering in a marketplace, note that the top-level `interface.displayName` belongs to the marketplace itself, not individual plugin entries, as specified in the schema documentation.

## Adding Optional Components

The scaffold script supports several flags that create empty directories or stub JSON files for specific component types. These options allow you to structure your plugin for future expansion:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-plugin \
  --with-skills \
  --with-hooks \
  --with-assets \
  --with-mcp \
  --with-apps

```

This command generates the following structure:

```

my-plugin/
├─ .codex-plugin/
│  └─ plugin.json
├─ skills/
├─ hooks/
├─ assets/
├─ .mcp.json          # stub {"mcpServers": {}}

└─ .app.json          # stub {"apps": {}}

```

- **`--with-skills`**: Creates a `skills/` directory forAI-powered capabilities
- **`--with-hooks`**: Adds a `hooks/` directory for lifecycle event handlers  
- **`--with-assets`**: Includes an `assets/` folder for static resources
- **`--with-mcp`**: Generates a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) stub for Model Context Protocol servers
- **`--with-apps`**: Creates a [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) stub for app definitions

## Registering with the Codex Marketplace

To make your plugin discoverable within the Codex ecosystem, you can automatically register it in the marketplace during scaffolding.

### Marketplace Entry Format

Add the `--with-marketplace` flag along with policy and category settings:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-plugin \
  --with-marketplace \
  --install-policy AVAILABLE \
  --auth-policy ON_INSTALL \
  --category Productivity

```

This updates the marketplace file (default location: `~/.agents/plugins/marketplace.json`) with an entry structured as:

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

```

### Policy Settings

The marketplace entry includes two critical policy fields:

- **`installation`**: Controls availability (e.g., `AVAILABLE`, `DISABLED`)
- **`authentication`**: Defines when authentication occurs (e.g., `ON_INSTALL`, `NEVER`)

You can specify a custom marketplace path using the `--marketplace-path` argument if you want to register the plugin in a repository-local file rather than the default user directory.

## Validating Your Plugin Structure

After editing your plugin files or generating new components, verify the JSON schema validity using the validation helper:

```bash
python3 .agents/skills/plugin-creator/scripts/quick_validate.py \
  .agents/skills/plugin-creator

```

This script checks that your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and marketplace entries conform to the expected schemas, catching syntax errors or missing required fields before deployment.

## 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 complete Codex plugin structure with a single command.
- **Follow naming conventions** enforced by `normalize_plugin_name` and `validate_plugin_name` (lower-case kebab-case, ≤ 64 characters).
- **Locate the manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and customize the `interface` block to control Codex UI presentation.
- **Add components** using flags like `--with-skills`, `--with-mcp`, and `--with-apps` to create ready-to-extend skeleton directories.
- **Register in the marketplace** using `--with-marketplace` with appropriate `--install-policy` and `--auth-policy` settings.
- **Validate your work** with [`quick_validate.py`](https://github.com/openai/plugins/blob/main/quick_validate.py) to ensure JSON schema compliance before distribution.

## Frequently Asked Questions

### Where does the plugin manifest file live in a Codex plugin structure?

The manifest file must reside at `<plugin-root>/.codex-plugin/plugin.json` within your plugin directory. This location is hardcoded in the Codex plugin architecture, and the scaffold script creates this path automatically when you run [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py).

### What naming conventions must I follow when creating a Codex plugin?

Plugin names must be in lower-case kebab-case format (e.g., `my-custom-plugin`) and cannot exceed 64 characters in length. The `normalize_plugin_name` function in the scaffold script automatically converts your input to this format, while `validate_plugin_name` enforces the character limit and pattern requirements.

### How do I add my custom plugin to the Codex marketplace?

Include the `--with-marketplace` flag when running the scaffold script, along with `--install-policy` and `--auth-policy` arguments. This adds an entry to `~/.agents/plugins/marketplace.json` (or a custom path specified with `--marketplace-path`) containing the plugin name, source location, policy settings, and display category.

### What optional components can I include when scaffolding a Codex plugin?

The scaffold script supports five optional component flags: `--with-skills` for AI capabilities, `--with-hooks` for event handlers, `--with-assets` for static files, `--with-mcp` for Model Context Protocol configuration, and `--with-apps` for app definitions. Each flag creates the appropriate directory structure or JSON stub file within your plugin root.