# How to Create a New Codex Plugin with a .codex-plugin/plugin.json Manifest > Learn to create a new Codex plugin by defining its metadata and capabilities with a .codex-plugin/plugin.json manifest file. Follow the official schema for seamless integration. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-07-04 --- **Create a directory under `plugins/` containing a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file that defines metadata, interface settings, and capabilities according to the Codex plugin schema.** The openai/plugins repository provides the reference implementation and JSON schema for building custom Codex plugins. At the core of every plugin is the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file, which tells the Codex runtime how to discover, display, and execute your integration. ## Required Directory Structure for Codex Plugins Every Codex plugin lives in its own folder under the `plugins/` directory. The runtime requires a specific layout to recognize and load your extension: ``` plugins// .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 ``` As documented in 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. All other files and directories are optional depending on whether your plugin requires custom assets, additional skills, or external app integrations. ## Understanding the .codex-plugin/plugin.json Manifest Schema The manifest must conform 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). This file defines the contract between your plugin and the Codex runtime. ### Top-Level Metadata Fields The root object of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) requires several descriptive fields: - **`name`**: A kebab-case identifier (e.g., `my-plugin`). - **`version`**: A semantic version string (e.g., `1.0.0`). - **`description`**: A brief summary of the plugin's purpose. - **`author`**: An object containing `name`, `email`, and `url`. - **`homepage`**: The documentation URL for the plugin. - **`repository`**: The source code URL. - **`license`**: An SPDX license identifier (e.g., `MIT`). - **`keywords`**: An array of search tags for marketplace discovery. - **`apps`**: Relative path to the optional [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file (e.g., `"./.app.json"`). ### The Interface Configuration Object The **`interface`** object contains the fields that the Codex UI reads to render your plugin. According to the spec, this includes: - **`displayName`**: The human-readable name shown in the UI. - **`shortDescription`**: A one-line subtitle. - **`longDescription`**: Detailed markdown-supported description of capabilities. - **`developerName`**: The entity responsible for the plugin. - **`category`**: Classification such as `Research` or `Productivity`. - **`capabilities`**: An array of feature flags. - **`defaultPrompt`**: An array of suggested prompts (e.g., `["Find the most relevant highlights"]`). - **`composerIcon`** and **`logo`**: Relative paths to icon assets (e.g., `"./assets/app-icon.png"`). - **`websiteURL`**, **`privacyPolicyURL`**, **`termsOfServiceURL`**: Compliance and documentation links. ## Real-World Manifest Examples from the openai/plugins Repository The repository includes complete, production-ready plugins that demonstrate the schema implementation. ### 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: ```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 Configuration The [`plugins/monday-com/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/monday-com/.codex-plugin/plugin.json) file 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 Instead of manually creating directories and JSON files, use the provided scaffold utility 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 script automates the setup process by: 1. Normalizing and validating the plugin name. 2. Creating the directory tree including optional `skills/` and `assets/` folders. 3. Writing a placeholder [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) populated with `[TODO]` markers for required fields. 4. Optionally updating [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) for discovery. Execute 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 and interface configuration. ## Handling Assets and Optional Configuration Files If your plugin requires visual assets, create an `assets/` directory within your plugin folder and store icons, logos, or screenshots there. Reference these files 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 assets and displays them in the plugin marketplace. You may also include: - **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)**: Defines app-specific integration settings. - **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)**: Configures MCP (Model Context Protocol) server descriptors. - **`skills/`**: Contains additional skill implementations referenced by your plugin. ## Registering Your Plugin in marketplace.json For the Codex runtime to discover your plugin, it must be registered in a [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file. This file controls the `installPolicy`, `authPolicy`, and `category` under which your plugin appears in the UI. The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script can automatically insert this entry when you pass the `--with-marketplace` flag, or you can manually add the entry following the schema in the repository documentation. ## Summary - Create a directory under `plugins//` with a `.codex-plugin/` subdirectory containing the mandatory [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file. - Define the manifest according to the 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), including top-level metadata and the `interface` object. - Populate the `interface` fields such as `displayName`, `category`, `defaultPrompt`, and asset paths to control UI presentation. - Store visual assets in an `assets/` folder and reference them using relative paths like `"./assets/app-icon.png"`. - 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 automatically. - Register the plugin in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) to enable discovery by the Codex runtime. ## Frequently Asked Questions ### What is the exact file path for the Codex plugin manifest? The manifest must be located at `plugins//.codex-plugin/plugin.json` relative to the repository root. This specific path structure is required for the Codex runtime to identify the directory as a valid plugin package. ### Which fields are mandatory in the plugin.json file? Required top-level fields include `name` (kebab-case), `version`, `description`, `author`, `license`, and `interface`. Within the `interface` object, `displayName`, `shortDescription`, `longDescription`, and `category` are essential for proper rendering in the Codex UI. ### Can I generate a Codex plugin scaffold automatically? Yes. Run `python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py --with-assets --with-apps --with-marketplace` to generate the complete directory structure, placeholder manifest, and marketplace entry. You must then edit the generated JSON to replace `[TODO]` placeholders with real values. ### How do I reference icons and screenshots in the manifest? Place image files in an `assets/` folder within your plugin directory and reference them using relative paths such as `"./assets/app-icon.png"` in the `composerIcon`, `logo`, and `screenshots` fields of the `interface` object.