# How to Create a Custom Plugin for Codex: Complete Scaffolding Guide

> Create a custom plugin for Codex quickly using the openai plugins repository. Generate a full structure, manifest, and marketplace registration with one command.

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

---

**The fastest way to create a custom plugin for Codex is using the `plugin-creator` skill in the openai/plugins repository, which generates a complete directory structure, a validated [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest, and optional marketplace registration in a single command.**

The openai/plugins repository provides a production-ready scaffolding system that eliminates manual boilerplate when building Codex extensions. This guide explains how to use the built-in [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script to generate plugin skeletons, configure manifests according to the official JSON specification, and register your work for discovery inside the Codex UI.

## Architecture of the Plugin-Creator Skill

The scaffolding system centers on [`.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), a command-line tool that orchestrates three distinct operations:

1. **Directory Generation** – Creates the plugin root folder and populates it with a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest containing placeholder metadata.
2. **Component Stubs** – Optionally creates empty subdirectories for `skills/`, `hooks/`, `assets/`, and stub files for MCP ([`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)) and apps ([`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)) based on flags you provide.
3. **Marketplace Integration** – When requested, appends an entry to a [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file (default path: `~/.agents/plugins/marketplace.json`) following the schema defined in [`references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/references/plugin-json-spec.md).

The script enforces naming conventions through two internal helpers: `normalize_plugin_name` converts identifiers to lower-case kebab-case, while `validate_plugin_name` ensures the result does not exceed 64 characters.

## Generating a Basic Plugin Skeleton

Run the scaffold script with your desired plugin name to create the minimum viable structure:

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

```

This command creates `~/plugins/my-plugin/` (or your current working directory) containing:

- [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) – A manifest with placeholder fields for `name`, `version`, `author`, and an empty `interface` block that drives the Codex UI presentation.
- The root folder itself, ready for custom code.

### Understanding the Manifest Schema

The generated [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) conforms to the specification 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 requires top-level metadata and an `interface` object that controls how Codex renders your plugin in the sidebar and command palette. Always reference this spec when adding fields, as it defines validation rules for the marketplace entry format.

## Adding Optional Components

Beyond the basic skeleton, the scaffold script supports flags that generate ready-to-extend directories and stub files:

- **`--with-skills`** – Creates a `skills/` directory for custom Codex skills.
- **`--with-hooks`** – Creates a `hooks/` directory for lifecycle intercepts.
- **`--with-assets`** – Creates an `assets/` directory for static resources.
- **`--with-mcp`** – Generates a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) stub containing `{"mcpServers": {}}`.
- **`--with-apps`** – Generates a [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) stub containing `{"apps": {}}`.

Combine flags to scaffold a full-featured plugin:

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

```

Resulting structure:

```

my-plugin/
├─ .codex-plugin/
│  └─ plugin.json
├─ skills/
├─ hooks/
├─ assets/
├─ .mcp.json
└─ .app.json

```

## Registering Your Plugin in the Marketplace

To make your plugin discoverable inside the Codex UI, include the `--with-marketplace` flag and supply policy parameters:

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

```

The script updates [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) with an entry matching the schema defined in the spec file:

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

```

Note that the marketplace's top-level `interface.displayName` belongs to the marketplace itself, not individual plugin entries, as outlined in lines 13-20 of the specification.

## Validating Plugin Integrity

After editing your manifest or adding new components, verify JSON compliance using the validation helper referenced in the skill documentation:

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

```

This utility checks that [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and any marketplace entries adhere to the expected schemas before you attempt to load the plugin in Codex.

## Summary

- **Scaffold instantly** – 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 generate a complete plugin directory with one command.
- **Locate the manifest** – The core configuration lives at `<plugin-root>/.codex-plugin/plugin.json` and must follow the schema in [`references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/references/plugin-json-spec.md).
- **Name correctly** – Plugin names are normalized to kebab-case and limited to 64 characters via internal validation functions.
- **Extend with flags** – Add `--with-skills`, `--with-hooks`, `--with-assets`, `--with-mcp`, or `--with-apps` to pre-create component directories.
- **Publish locally** – Use `--with-marketplace` to register the plugin in `~/.agents/plugins/marketplace.json` with configurable installation and authentication policies.
- **Validate early** – Run [`quick_validate.py`](https://github.com/openai/plugins/blob/main/quick_validate.py) to catch JSON schema errors before runtime.

## Frequently Asked Questions

### Where is the plugin manifest stored after scaffolding?

The manifest is written to [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) inside your generated plugin directory. This location is hard-coded in the scaffold script and is the only path Codex scans when loading local plugins.

### What naming conventions does the scaffold script enforce?

The script applies two validation layers: `normalize_plugin_name` converts any input to lower-case kebab-case (e.g., `My Plugin` becomes `my-plugin`), and `validate_plugin_name` rejects names longer than 64 characters. These rules ensure compatibility with the Codex marketplace indexing system.

### How do I add custom skills or hooks to my plugin?

Pass the `--with-skills` and/or `--with-hooks` flags when running [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py). These generate empty `skills/` and `hooks/` directories where you can add implementation files; the scaffold script does not populate logic, only the folder structure and placeholder JSON where required.

### Can I change the marketplace file location?

Yes. By default, the script writes to `~/.agents/plugins/marketplace.json`. Override this by passing `--marketplace-path <custom_path>` to point to a repository-local or shared marketplace file, useful for team development or CI/CD pipelines.