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

> Learn how to create a Codex plugin using a plugin.json manifest. Discover essential metadata for discovery, capabilities, and UI rendering.

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

---

**A Codex plugin is defined by a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is the only mandatory component. As documented in the repository's [`README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/readwise/.codex-plugin/plugin.json), implements the Research category with a complete interface configuration:

```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 Example

The Monday.com plugin, located at [`plugins/monday-com/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/monday-com/.codex-plugin/plugin.json), configures the Productivity category:

```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

The repository provides a 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) 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`](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) for discovery.

Generate a new plugin skeleton by running:

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with valid `name`, `version`, `description`, `author`, and `interface` fields. Optional components include `assets/`, `skills/`, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) using relative paths such as `"./assets/app-icon.png"` for the `composerIcon` and `logo` fields within the `interface` object.