How to Structure plugin.json with All Required Fields for OpenAI Plugins

The OpenAI Codex plugin system requires a manifest file at .codex-plugin/plugin.json containing 12 top-level fields and a nested interface object with 14 additional fields, all strictly enforced by the validator at plugins/plugin-eval/src/evaluators/plugin.js.

Every plugin in the openai/plugins repository must include a complete plugin.json manifest to be discovered and loaded by the Codex system. This JSON file defines your plugin's identity, versioning, UI presentation, and resource paths according to the strict validation rules specified in the reference documentation.

Required Top-Level Fields

The manifest must include these fields at the root level, as defined in .agents/skills/plugin-creator/references/plugin-json-spec.md:

• name – A kebab-case identifier that must match the plugin folder name exactly; serves as the component namespace.
• version – Semantic version string (e.g., "1.2.0") used for upgrade checks.
• description – One-sentence summary displayed in marketplace listings.
• author – Object containing name, email, and url for the publisher.
• homepage – URL for documentation or help pages.
• repository – Link to the source code repository.
• license – SPDX-compatible license string (e.g., "MIT").
• keywords – Array of searchable tags (e.g., ["automation", "productivity"]).
• skills – Relative path to the folder containing skill implementations.
• hooks – Path to a hooks.json file (provide even if empty).
• mcpServers – Path to the MCP configuration file (.mcp.json).
• apps – Path to the optional app manifest (.app.json).

Path Conventions

All path values—including skills, hooks, mcpServers, apps, and asset references—must start with ./ and be relative to the plugin root directory.

Required Interface Object Fields

The interface object supplies UI metadata for the ChatGPT plugin marketplace and composer. Omitting these fields causes the plugin to render incorrectly in the UI.

• displayName – Human-readable title shown on the plugin card.
• shortDescription – Subtitle displayed in compact views.
• longDescription – Full description for the detail page.
• developerName – Publishing organization name (e.g., "OpenAI").
• category – Broad grouping (e.g., "Productivity").
• capabilities – Array of features (e.g., ["Interactive", "Write"]).
• websiteURL – Public website for the plugin.
• privacyPolicyURL – URL to the privacy policy.
• termsOfServiceURL – URL to the terms of service.
• defaultPrompt – Array of up to three starter prompts for the Composer UI.
• brandColor – Hex color code for the plugin card background.
• composerIcon – Path to the icon shown in the Composer.
• logo – Path to the logo displayed on the plugin card.
• screenshots – Array of PNG file paths (under ./assets/) for marketplace previews.

Validation and Error Handling

The built-in validator at plugins/plugin-eval/src/evaluators/plugin.js enforces every required field at load time. If any field is missing, the plugin is rejected with a specific error message such as:

plugin.json is missing the required `name` field.

Missing the interface object entirely allows the plugin to load but prevents proper rendering in the ChatGPT marketplace UI.

Complete plugin.json Example

Below is a minimal, fully-populated manifest that satisfies all validator requirements. Replace placeholder values with your plugin-specific information.

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "A short description of what the plugin does",
  "author": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "url": "https://github.com/janedoe"
  },
  "homepage": "https://github.com/janedoe/my-awesome-plugin#readme",
  "repository": "https://github.com/janedoe/my-awesome-plugin",
  "license": "MIT",
  "keywords": ["automation", "productivity"],
  "skills": "./skills/",
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Awesome Plugin",
    "shortDescription": "Quickly do awesome things",
    "longDescription": "Detailed description of the plugin’s capabilities, usage, and benefits.",
    "developerName": "OpenAI",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"],
    "websiteURL": "https://myawesomeplugin.com",
    "privacyPolicyURL": "https://myawesomeplugin.com/privacy",
    "termsOfServiceURL": "https://myawesomeplugin.com/terms",
    "defaultPrompt": [
      "Summarize my inbox",
      "Create a new task in Linear",
      "Generate a meeting agenda"
    ],
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot1.png",
      "./assets/screenshot2.png",
      "./assets/screenshot3.png"
    ]
  }
}

Directory Structure and Naming Consistency

Maintain consistency between your folder structure and manifest values to ensure proper discovery:

• Manifest location – Must be at .codex-plugin/plugin.json exactly.
• Naming consistency – The folder name, the name field value, and the entry in marketplace.json must all match exactly using kebab-case with no spaces.
• Asset organization – Store icons and screenshots in ./assets/ and reference them with relative paths starting with ./.

A typical plugin layout looks like this:

my-awesome-plugin/
├── .codex-plugin/
│   └── plugin.json          ← manifest
├── skills/
│   └── ...                  ← skill implementations
├── hooks.json               ← hook configuration
├── .mcp.json                ← MCP server config
├── .app.json                ← app manifest
└── assets/
    ├── icon.png
    ├── logo.png
    └── screenshot1.png

Summary

• The plugin.json manifest requires 12 top-level fields and an interface object containing 14 UI-specific fields.
• All paths must be relative starting with ./ and point to existing files.
• The validator at plugins/plugin-eval/src/evaluators/plugin.js rejects manifests missing any required field.
• The folder name must match the name field exactly in kebab-case format.
• Reference documentation is located at .agents/skills/plugin-creator/references/plugin-json-spec.md.

Frequently Asked Questions

What happens if I omit a required field in plugin.json?

The validator in plugins/plugin-eval/src/evaluators/plugin.js will reject the plugin at load time, displaying a specific error message indicating which required field is missing. The plugin will not be available in the marketplace until all required fields are present.

Can I use absolute paths for the skills or assets fields?

No. According to the path conventions in the openai/plugins repository, all path values—including skills, hooks, mcpServers, apps, and asset references—must use relative paths starting with ./ and be relative to the plugin root directory.

How does the name field in plugin.json relate to the folder structure?

The name field must match the plugin folder name exactly using kebab-case (e.g., my-awesome-plugin). This consistency is required for the component namespace resolution and marketplace entry alignment. The validator checks this correspondence when loading the plugin.

Where can I find the official specification for all plugin.json fields?

The authoritative specification is located at .agents/skills/plugin-creator/references/plugin-json-spec.md in the openai/plugins repository. This document defines every field, including type requirements, path conventions, and validation rules enforced by the plugin evaluator.

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