# Creating a .codex-plugin/plugin.json Manifest File for OpenAI Codex Plugins

> Learn to create a .codex-plugin/plugin.json manifest file for OpenAI Codex plugins. Define metadata UI and capabilities using the JSON schema specification.

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

---

**A Codex plugin requires a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file that defines the plugin's metadata, UI presentation, and capabilities according to the JSON schema specification in the OpenAI Plugins repository.**

The OpenAI Plugins repository provides a standardized framework for building custom Codex plugins. Every plugin must include a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file that enables the Codex runtime to discover, render, and execute the plugin's functionality. This guide walks through the directory structure, schema requirements, and automation tools available in the `openai/plugins` repository.

## Required Directory Structure

Create a dedicated folder under `plugins/` with your chosen plugin name. The repository requires a specific layout where the manifest file lives inside a hidden `.codex-plugin/` directory.

```

plugins/<my-plugin>/
    .codex-plugin/
        plugin.json
    assets/               # optional UI assets (icons, 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) describes this layout and confirms that the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is mandatory for the Codex runtime to recognize the plugin.

## Manifest Schema and Required Fields

The manifest must follow 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). The top-level fields include:

- **`name`**: Kebab-case identifier (e.g., `my-plugin`).
- **`version`**: Semantic version string.
- **`description`**: Short purpose summary.
- **`author`**: Object with `name`, `email`, and `url`.
- **`homepage`**: Documentation URL.
- **`repository`**: Source-code URL.
- **`license`**: SPDX license identifier.
- **`keywords`**: Search tags for discovery.
- **`apps`**: Path to the optional [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file.
- **`interface`**: UI-presentation block containing display names, descriptions, icons, and categories.

### Interface Configuration

The `interface` object contains the fields that the Codex UI reads to render the plugin in the marketplace and composer. Required sub-fields include:

- **`displayName`**: Human-readable name shown in the UI.
- **`shortDescription`**: One-line subtitle.
- **`longDescription`**: Detailed markdown description of capabilities.
- **`category`**: Classification such as `Research` or `Productivity`.
- **`defaultPrompt`**: Array of suggested prompts to help users get started.
- **`composerIcon`**: Relative path to the icon displayed in the composer (e.g., `./assets/app-icon.png`).
- **`logo`**: Relative path to the logo used in the marketplace.

Additional fields include `developerName`, `capabilities`, `screenshots`, `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL`.

## Real-World Examples from the Repository

The `openai/plugins` repository provides production-ready examples that demonstrate the schema in practice.

### Readwise Plugin Example

The Readwise plugin at [`plugins/readwise/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/readwise/.codex-plugin/plugin.json) implements a complete Research category manifest:

```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, and any content saved to your Reader library.\n\nMore than that, it can do basically anything you can do in Reader! Triage your inbox, organize your library, catch up on your feed, and much more -- just ask :)",
    "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 at [`plugins/monday-com/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/monday-com/.codex-plugin/plugin.json) shows a Productivity category implementation:

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

The repository ships a helper 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 the creation of the directory structure and manifest file.

The script performs the following actions:

1. Normalizes and validates the plugin name.
2. Creates the directory tree including optional `skills/`, `assets/`, [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files.
3. Writes a placeholder [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) populated with the fields outlined in the specification.
4. Optionally updates a [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file for discovery.

Run 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, edit the generated [`plugins/my-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/.codex-plugin/plugin.json) to replace the `[TODO]` placeholders with your actual metadata.

## Asset Handling and Path References

If you provide UI assets such as icons, logos, or screenshots, place them under the `assets/` directory and reference them relative to the plugin root. The Readwise and Monday.com examples both use `"./assets/app-icon.png"` for the `composerIcon` and `logo` fields. These assets are bundled with the plugin and displayed in the Codex plugin marketplace.

## Registering Your Plugin in the Marketplace

For a plugin to be discoverable by Codex, its entry must appear in a [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file. The scaffold script can automatically insert an entry with the appropriate `installPolicy`, `authPolicy`, and `category`. The marketplace registration connects your [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest to the Codex UI discovery system.

## Summary

- **Create a directory** under `plugins/<name>/` with a `.codex-plugin/` subdirectory.
- **Add a [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file** that follows 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).
- **Include required metadata**: `name`, `version`, `description`, `author`, `interface`, and asset paths.
- **Use the scaffold script** [`.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 generate boilerplate automatically.
- **Register in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json)** to make the plugin discoverable in the Codex UI.

## Frequently Asked Questions

### What is the purpose of the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file?

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file serves as the mandatory metadata manifest that allows the Codex runtime to discover your plugin, understand its capabilities, and render it properly in the user interface. Without this file in the correct location, the Codex system cannot recognize or load your plugin.

### Can I create a Codex plugin without using the scaffold script?

Yes, you can manually create the directory structure and write the JSON file. However, using [`.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) ensures you follow the correct naming conventions, directory layout, and schema requirements while generating placeholder values that guide you through the required fields.

### Where should I place icons and images for my plugin?

Place all UI assets in an `assets/` folder at the root of your plugin directory. Reference these files in your [`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, as demonstrated in the Readwise and Monday.com examples.

### What fields are required in the `interface` object of the manifest?

The `interface` object requires `displayName`, `shortDescription`, `longDescription`, `category`, `defaultPrompt`, `composerIcon`, and `logo` to properly render in the Codex UI. You should also include `developerName`, `websiteURL`, and `privacyPolicyURL` to meet the marketplace listing requirements specified in the plugin JSON schema.