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

A custom Codex plugin is defined by a directory containing a .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 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 manifest inside.

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

According to the repository's README.md, the .codex-plugin/plugin.json file is mandatory. The assets/, skills/, .app.json, and .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. 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 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 file demonstrates a fully populated Research-category manifest. It references the optional .app.json integration file and supplies complete branding and prompt data.

{
  "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 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, 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, and .app.json.
3. Writes a draft .codex-plugin/plugin.json conforming to the spec.
4. Optionally appends an entry to marketplace.json for discovery.

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

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

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "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 manifest.
• The manifest schema is defined in .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 and plugins/monday-com/.codex-plugin/plugin.json demonstrate valid Research and Productivity configurations.
• Use .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 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 file. Optional folders like assets/ and skills/, along with optional files like .app.json and .mcp.json, can be added if your plugin requires UI resources or custom skills.

Which fields are mandatory in .codex-plugin/plugin.json?

As specified in the schema at .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 is also required.

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

Discovery requires an entry in a marketplace.json file. The scaffold script .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 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.

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