How to Create a Codex Plugin with a plugin.json Manifest

A Codex plugin is defined by a .codex-plugin/plugin.json manifest file that supplies metadata for discovery, capabilities, and UI rendering.

The openai/plugins repository hosts the reference implementation and specification for building custom Codex plugins. To create a Codex plugin, you must construct a directory containing a valid manifest that conforms to the JSON schema documented in .agents/skills/plugin-creator/references/plugin-json-spec.md, allowing the Codex runtime to discover and render your integration.

Required Directory Structure

Every Codex plugin resides in a dedicated 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 UI assets (icons, screenshots)

    skills/                  # Optional skill implementations

    .app.json                # Optional app integration manifest

    .mcp.json                # Optional MCP server descriptor

The .codex-plugin/plugin.json file is the only mandatory component. As documented in the repository's README.md, the Codex runtime specifically looks for this path to load plugin metadata.

The plugin.json Manifest Schema

The manifest must validate against the schema defined in .agents/skills/plugin-creator/references/plugin-json-spec.md. This file controls how the plugin appears in the marketplace and how Codex interacts with your integration.

Core Metadata Fields

The top-level object requires specific fields that identify the plugin and its origin:

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

Interface Configuration

The interface object determines how Codex displays your plugin to users:

• displayName: Human-readable name shown in the UI.
• shortDescription: One-line subtitle.
• longDescription: Detailed markdown-supported description.
• developerName: Organization or individual responsible for the plugin.
• category: Classification such as Research or Productivity.
• capabilities: Array of feature flags.
• defaultPrompt: Array of suggested prompts to display to users.
• composerIcon: Relative path to the icon shown in the composer (e.g., ./assets/app-icon.png).
• logo: Relative path to the logo asset.
• websiteURL, privacyPolicyURL, termsOfServiceURL: Compliance and informational links.

Real-World Examples from the Repository

The openai/plugins repository includes production-quality examples that demonstrate valid manifest patterns.

Readwise Plugin Example

The Readwise plugin, located at plugins/readwise/.codex-plugin/plugin.json, implements the Research category with a complete interface configuration:

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

The Monday.com plugin, located at plugins/monday-com/.codex-plugin/plugin.json, configures the Productivity category:

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

The repository provides a scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py that automates directory creation and generates a template manifest. This utility:

1. Validates and normalizes the plugin name.
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 for discovery.

Generate a new plugin skeleton by running:

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

After execution, edit .codex-plugin/plugin.json to replace placeholder values with your actual metadata.

Asset Handling and Marketplace Registration

Place UI assets such as icons and screenshots in the assets/ directory and reference them using relative paths from the plugin root. For example, "./assets/app-icon.png" correctly resolves when the plugin is packaged.

To make your plugin discoverable, add an entry to a marketplace.json file at the personal or repository level. The scaffold script can automatically insert this entry with appropriate installPolicy, authPolicy, and category values as defined in the marketplace specification.

Summary

• A valid Codex plugin requires a .codex-plugin/plugin.json manifest in a directory under plugins/.
• The manifest must specify core metadata (name, version, author) and an interface object controlling UI presentation.
• Reference implementations in plugins/readwise/ and plugins/monday-com/ demonstrate production-ready configurations.
• Use .agents/skills/plugin-creator/scripts/create_basic_plugin.py to scaffold new plugins with the correct directory structure and template manifest.
• Assets referenced in the manifest should be stored in assets/ using relative paths.

Frequently Asked Questions

What is the minimum required structure for a Codex plugin?

The absolute minimum is a directory containing .codex-plugin/plugin.json with valid name, version, description, author, and interface fields. Optional components include assets/, skills/, .app.json, and .mcp.json files.

How do I validate my plugin.json manifest?

Compare your manifest against the official schema in .agents/skills/plugin-creator/references/plugin-json-spec.md. The scaffold script performs basic validation during creation, and you should verify that all [TODO] placeholders are replaced before distribution.

Can I create a Codex plugin without the scaffold script?

Yes. Manually create the directory structure under plugins/ and write the .codex-plugin/plugin.json file according to the specification. The scaffold script is a convenience tool, not a requirement, though it ensures correct boilerplate and directory conventions.

Where should I store plugin assets like icons and logos?

Store static assets in an assets/ folder at the plugin root. Reference these files in plugin.json using relative paths such as "./assets/app-icon.png" for the composerIcon and logo fields within the interface object.

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