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

> Learn to create a custom Codex plugin using the .codex-plugin/plugin.json manifest file. Discover how to define discovery, rendering, and execution for your plugin.

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

---

**A custom Codex plugin is defined by a directory containing a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file that tells the Codex runtime how to discover, render, and execute the plugin.**

The `openai/plugins` repository provides the official schema, production examples such as Readwise and Monday.com, and a Python scaffold utility to generate a complete plugin skeleton. To create a custom Codex plugin with the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest structure, you need a correctly structured file placed in a directory under `plugins/` that follows the spec defined in the repository.

## Required Directory Layout

Every Codex plugin lives in its own folder under the `plugins/` directory. At minimum, the folder must contain a `.codex-plugin/` subdirectory with a [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest inside.

```text
plugins/<my-plugin>/
    .codex-plugin/
        plugin.json
    assets/
    skills/
    .app.json
    .mcp.json

```

According to the repository's [`README.md`](https://github.com/openai/plugins/blob/main/README.md), the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is mandatory. The `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 are optional depending on whether your plugin provides UI resources, skill implementations, or app integrations.

## Manifest Structure and Schema

The authoritative JSON schema is 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 manifest separates top-level metadata from UI presentation data so the Codex runtime can discover and render the plugin correctly.

### Top-Level Metadata Fields

- **`name`** — Kebab-case identifier (e.g., `my-plugin`).
- **`version`** — Semantic version string.
- **`description`** — Short summary of the plugin's purpose.
- **`author`** — Object containing `name`, `email`, and `url`.
- **`homepage`** — Link to documentation.
- **`repository`** — Source-code URL.
- **`license`** — SPDX license identifier.
- **`keywords`** — Array of search tags.
- **`apps`** — Relative path to an optional [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file.
- **`interface`** — Object that controls how the plugin appears in the Codex UI.

### Interface Presentation Block

The `interface` object supplies all visual and marketing content rendered by Codex:

- **`displayName`** — Human-readable name shown in the marketplace.
- **`shortDescription`** — One-line subtitle.
- **`longDescription`** — Detailed markdown-enabled description.
- **`category`** — Marketplace category (e.g., `Research`, `Productivity`).
- **`defaultPrompt`** — Array of suggested prompts presented to users.
- **`developerName`** — Organization or individual who authored the plugin.
- **`composerIcon`** and **`logo`** — Relative paths to image assets.
- **`websiteURL`**, **`privacyPolicyURL`**, **`termsOfServiceURL`** — Compliance links.
- **`capabilities`** and **`screenshots`** — Optional feature flags and image arrays.

### Production Example: Readwise Plugin

The [`plugins/readwise/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/readwise/.codex-plugin/plugin.json) file demonstrates a fully populated Research-category manifest. It references the optional [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) integration file and supplies complete branding and prompt data.

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

```

A second production example in [`plugins/monday-com/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/monday-com/.codex-plugin/plugin.json) follows the exact same schema but uses the `Productivity` category. Both files validate against the spec and prove that category and prompt content are the primary variables between plugins.

## Using the Scaffold Generator

The repository ships [`.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), a CLI utility that generates a complete plugin directory. It pre-populates the manifest with `[TODO]` placeholders so you can fill in production values quickly.

The script performs four operations:

1. Normalizes and validates the requested plugin name.
2. Creates the directory tree, optionally including `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).
3. Writes a draft [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) conforming to the spec.
4. Optionally appends an entry to [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) for discovery.

Run it from the repository root with the plugin name and desired flags:

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

```

After execution, open [`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 your production values. You can then add custom skills or assets before testing the plugin in Codex.

## Referencing Assets and Marketplace Registration

If you provide icons or screenshots, place them under `plugins/<my-plugin>/assets/` and reference them with relative paths from the plugin root. For example, the Readwise and Monday.com manifests both use `"./assets/app-icon.png"` for their `composerIcon` and `logo` fields.

For Codex to surface the plugin in its marketplace UI, an entry must exist in a [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file. The scaffold script can inject this entry automatically with the correct `installPolicy`, `authPolicy`, and `category`. If you are writing it manually, consult the Marketplace section of [`.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) for the exact entry structure.

## Minimal plugin.json Template

If you prefer to write the manifest by hand, use this boilerplate as your starting point. It includes all required top-level fields and a fully populated `interface` object.

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/my-plugin",
  "repository": "https://github.com/yourname/my-plugin",
  "license": "MIT",
  "keywords": ["my", "plugin"],
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "One-line subtitle",
    "longDescription": "Detailed description of what the plugin does.",
    "developerName": "Your Name",
    "category": "Productivity",
    "capabilities": [],
    "websiteURL": "https://yourplugin.example.com",
    "privacyPolicyURL": "https://yourplugin.example.com/privacy",
    "termsOfServiceURL": "https://yourplugin.example.com/terms",
    "defaultPrompt": [
      "Do something with my plugin"
    ],
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png"
  }
}

```

## Summary

- A 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 is 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) and separates top-level metadata from the UI `interface` block.
- Production examples in [`plugins/readwise/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/readwise/.codex-plugin/plugin.json) and [`plugins/monday-com/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/monday-com/.codex-plugin/plugin.json) demonstrate valid Research and Productivity 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 directories, manifests, and optional marketplace entries automatically.
- Reference UI assets with relative paths from the plugin root, and register the plugin in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) for Codex discovery.

## Frequently Asked Questions

### What is the required directory structure for a Codex plugin?

A Codex plugin must live in a folder under `plugins/<name>/` and contain at least a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file. Optional folders like `assets/` and `skills/`, along with optional files like [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), can be added if your plugin requires UI resources or custom skills.

### Which fields are mandatory in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)?

As specified in the schema at [`.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), every manifest must include `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and the `interface` object. If your plugin integrates with an external app, the `apps` field pointing to [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) is also required.

### How do I register my plugin so Codex can discover it?

Discovery requires an entry in a [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file. 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) can insert this entry automatically when invoked with the `--with-marketplace` flag. The entry includes `installPolicy`, `authPolicy`, and the plugin category so Codex can render it in the marketplace UI.

### Can I generate a Codex plugin automatically instead of writing files by hand?

Yes. The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script in `.agents/skills/plugin-creator/scripts/` generates the full directory tree, a draft manifest with `[TODO]` placeholders, and optional supporting files. Run it with flags such as `--with-assets`, `--with-skills`, `--with-apps`, and `--with-marketplace` to produce a ready-to-edit skeleton.