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

> Learn to build a custom Codex plugin using the essential .codex-plugin/plugin.json manifest file. Define metadata UI and capabilities for your plugin.

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

---

**A custom Codex plugin requires a directory containing a mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/README.md) explicitly states that the **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) file (e.g., [`./.app.json`](https://github.com/openai/plugins/blob/main/./.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`](https://github.com/openai/plugins/blob/main/plugins/readwise/.codex-plugin/plugin.json), this manifest defines a Research-category plugin with rich descriptive content and asset references:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/monday-com/.codex-plugin/plugin.json) file demonstrates a Productivity-category integration with a focus on MCP connectivity:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py)** script located at [`.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). 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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with `[TODO]` markers for required fields.
4. Optionally updates [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) with the plugin's entry.

Invoke the script from the repository root:

```bash
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) generates a complete skeleton, including optional [`marketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.