How to Create a Custom Codex Plugin with the .codex-plugin/plugin.json Manifest

A custom Codex plugin requires a directory containing a mandatory .codex-plugin/plugin.json manifest file that defines metadata, UI presentation, and capabilities for the Codex runtime.

Creating a custom Codex plugin involves structuring a dedicated directory and authoring a machine-readable manifest that the runtime consumes. According to the openai/plugins repository, the .codex-plugin/plugin.json file serves as the single source of truth for plugin discovery, capability exposure, and marketplace rendering. This guide walks through the exact directory layout, schema requirements, and automation tools provided by the maintainers.

Required Directory Structure

Every plugin must reside in its own folder under the plugins/ directory. The structure follows a convention that separates mandatory configuration from optional assets and skill implementations:

plugins/<my-plugin>/
    .codex-plugin/
        plugin.json          # Mandatory manifest

    assets/                   # Optional icons and screenshots

    skills/                   # Optional skill implementations

    .app.json                 # Optional app integration manifest

    .mcp.json                 # Optional MCP server descriptor

The repository's README.md explicitly states that the .codex-plugin/plugin.json file is mandatory, while other files and directories are optional depending on your plugin's complexity.

Understanding the plugin.json Manifest Schema

The manifest must validate against the JSON schema documented in .agents/skills/plugin-creator/references/plugin-json-spec.md. As implemented in openai/plugins, the schema divides into top-level metadata and a nested interface object that controls UI presentation.

Top-Level Metadata Fields

These fields identify the plugin and its origin:

• name: Kebab-case identifier (e.g., my-plugin).
• version: Semantic version string (e.g., 1.0.0).
• description: Short summary of purpose.
• author: Object containing name, email, and url.
• homepage: Documentation or marketing URL.
• repository: Source code URL.
• license: SPDX license identifier (e.g., MIT).
• keywords: Array of search tags for discovery.
• apps: Relative path to the optional .app.json file (e.g., ./.app.json).

The Interface Object

The interface object contains fields that the Codex UI reads to render the plugin in the marketplace and composer:

• displayName: Human-readable name shown in the UI.
• shortDescription: Subtitle or tagline.
• longDescription: Detailed markdown-supported description.
• category: Classification such as Productivity or Research.
• defaultPrompt: Array of suggested prompts to display to users.
• composerIcon: Relative path to the icon used in the composer (e.g., ./assets/app-icon.png).
• logo: Relative path to the logo used in marketplace listings.
• developerName, websiteURL, privacyPolicyURL, termsOfServiceURL: Metadata for marketplace compliance.

Real-World Examples from the Repository

The openai/plugins repository provides production-grade reference implementations that demonstrate the schema in action.

Readwise Plugin Configuration

Located at plugins/readwise/.codex-plugin/plugin.json, this manifest defines a Research-category plugin with rich descriptive content and asset references:

{
  "name": "readwise",
  "version": "1.0.1",
  "description": "The official app for Readwise and Reader.",
  "author": {
    "name": "Readwise Inc.",
    "url": "https://readwise.io"
  },
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "keywords": [],
  "apps": "./.app.json",
  "interface": {
    "displayName": "Readwise",
    "shortDescription": "The official app for Readwise and Reader.",
    "longDescription": "The official app for Readwise and Reader. \n\nThis app allows you to have Codex semantically search through all of your highlights...",
    "developerName": "Readwise Inc.",
    "category": "Research",
    "capabilities": [],
    "defaultPrompt": [
      "Find the most relevant highlights in Readwise"
    ],
    "screenshots": [],
    "websiteURL": "https://readwise.io",
    "privacyPolicyURL": "https://readwise.io/privacy",
    "termsOfServiceURL": "https://readwise.io/tos",
    "composerIcon": "./assets/app-icon.png",
    "logo": "./assets/app-icon.png"
  },
  "homepage": "https://readwise.io"
}

Monday.com Plugin Configuration

The plugins/monday-com/.codex-plugin/plugin.json file demonstrates a Productivity-category integration with a focus on MCP connectivity:

{
  "name": "monday-com",
  "version": "1.0.1",
  "description": "A powerful MCP connector enabling AI agents to seamlessly interact with monday.com.",
  "author": {
    "url": "https://monday.com",
    "name": "Monday.com"
  },
  "homepage": "https://monday.com",
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "keywords": [],
  "apps": "./.app.json",
  "interface": {
    "displayName": "Monday.com",
    "shortDescription": "A powerful MCP connector enabling AI agents to seamlessly interact with monday.com.",
    "longDescription": "...",
    "category": "Productivity",
    "capabilities": [],
    "websiteURL": "https://monday.com",
    "privacyPolicyURL": "https://monday.com/l/privacy/privacy-policy/",
    "defaultPrompt": [
      "Check the marketing campaign status in monday.com"
    ],
    "screenshots": [],
    "composerIcon": "./assets/app-icon.png",
    "logo": "./assets/app-icon.png",
    "developerName": "Monday.com"
  }
}

Automating Plugin Creation with the Scaffold Script

Rather than creating files manually, use the create_basic_plugin.py script located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py. This utility automates directory creation, name normalization, and placeholder population.

The script performs four operations:

1. Normalizes and validates the plugin name against naming conventions.
2. Creates the directory tree, including optional skills/ and assets/ folders.
3. Writes a placeholder .codex-plugin/plugin.json with [TODO] markers for required fields.
4. Optionally updates marketplace.json with the plugin's entry.

Invoke the script from the repository root:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --with-assets --with-skills --with-apps --with-marketplace

After execution, navigate to plugins/my-plugin/.codex-plugin/plugin.json and replace all [TODO] placeholders with production values.

Asset Handling and Marketplace Registration

Place UI assets such as icons and screenshots in the assets/ directory and reference them using relative paths (e.g., "./assets/app-icon.png"). These assets bundle with the plugin and render in the Codex marketplace.

For the plugin to appear in the Codex marketplace UI, its entry must exist in a marketplace.json file. When using the --with-marketplace flag, the scaffold script automatically inserts an entry with appropriate installPolicy, authPolicy, and category fields derived from your manifest.

Summary

• A valid Codex plugin requires a directory under plugins/ containing a mandatory .codex-plugin/plugin.json manifest.
• The manifest schema defines top-level metadata (name, version, author) and an interface object controlling UI presentation (display name, icons, descriptions).
• Reference implementations in plugins/readwise/ and plugins/monday-com/ demonstrate production-ready configurations for Research and Productivity categories.
• The scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py generates a complete skeleton, including optional marketplace.json updates.
• Assets referenced in the manifest (icons, logos) must reside in the assets/ folder using relative paths.

Frequently Asked Questions

What is the minimum required structure for a Codex plugin?

The absolute minimum is a directory under plugins/<name>/ containing a .codex-plugin/plugin.json file with valid name, version, description, and interface fields. Optional directories like assets/ or skills/ depend on whether your plugin requires custom icons or specialized logic.

How do I validate my plugin.json manifest against the schema?

Compare your manifest against the authoritative specification documented in .agents/skills/plugin-creator/references/plugin-json-spec.md. The scaffold script performs basic validation during generation, but manual review against the Readwise and Monday.com examples ensures compliance with current runtime expectations.

Where should I place icons and screenshots for my plugin?

Store visual assets in the assets/ directory at the plugin root, then reference them in plugin.json using relative paths like "./assets/app-icon.png". The Codex runtime bundles these files during plugin installation and displays them in the marketplace and composer interfaces.

How does the Codex runtime discover my custom plugin?

The runtime discovers plugins through entries in a marketplace.json file. When you generate a plugin using the scaffold script with the --with-marketplace flag, it automatically appends an entry containing the plugin's metadata, install policies, and category, making it visible in the Codex UI.

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