How to Structure a Custom Codex Plugin: Complete Setup Guide

Use the create_basic_plugin.py scaffold script from the openai/plugins repository to generate a complete Codex plugin directory with a standardized 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, 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. 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:

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 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. 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 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:

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 stub for Model Context Protocol servers
• --with-apps: Creates a .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:

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:

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

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

This script checks that your 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 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 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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}