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

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 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 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, 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 manifest containing placeholder metadata.
2. Component Stubs – Optionally creates empty subdirectories for skills/, hooks/, assets/, and stub files for MCP (.mcp.json) and apps (.app.json) based on flags you provide.
3. Marketplace Integration – When requested, appends an entry to a marketplace.json file (default path: ~/.agents/plugins/marketplace.json) following the schema defined in 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:

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 – 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 conforms to the specification documented in .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 stub containing {"mcpServers": {}}.
• --with-apps – Generates a .app.json stub containing {"apps": {}}.

Combine flags to scaffold a full-featured plugin:

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:

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 with an entry matching the schema defined in the spec file:

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

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

This utility checks that 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 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.
• 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 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 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. 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.

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