How to Create a Codex Plugin Manifest (`.codex-plugin/plugin.json`) with All Required Fields

To create a valid Codex plugin manifest, place a plugin.json file inside a .codex-plugin directory at your repository root and populate it with the five mandatory top-level fields (name, version, description, author, interface) plus all thirteen required sub-fields within the interface object.

Every Codex plugin requires a machine-readable manifest that tells the system how to discover, load, and display your integration. According to the OpenAI plugins repository, this manifest must live at a specific path and contain required metadata fields to pass the evaluation suite. This guide explains the exact structure, validation logic, and file paths needed to create a marketplace-ready Codex plugin manifest.

File Location and Discovery

The manifest must reside in a folder named .codex-plugin at the root of your plugin repository. Codex’s plugin-evaluation code loads the manifest from this exact path, as implemented in plugins/plugin-eval/src/evaluators/plugin.js (lines 13-28). The loader specifically checks for the existence of .codex-plugin/plugin.json before proceeding with validation.

If the file is missing or misplaced, the evaluator returns an immediate error and halts the plugin loading process. Keep the directory name lowercase and ensure it sits at the repository root, not nested within subdirectories.

Required Top-Level Fields

Your plugin.json must contain five mandatory top-level keys. These fields supply the machine-readable metadata that Codex uses for identification and versioning.

Field	Type	Purpose
name	string	Unique, kebab-case identifier used as the component namespace
version	string	Semantic version (e.g., 1.0.0)
description	string	Short summary of the plugin’s purpose
author	object	Publisher identity containing name, email, and url
interface	object	UI-level metadata that tells the marketplace how to display the plugin

The author object requires three sub-fields: name (display name), email (contact address), and url (website or profile link). While fields like homepage, repository, license, keywords, skills, hooks, mcpServers, and apps are optional, they are highly recommended for discoverability and correct asset routing.

Required Interface Fields

The interface object contains thirteen required sub-fields that control how your plugin appears in the Codex marketplace. Missing any of these triggers validation errors in the plugin-eval step.

Sub-field	Type	Description
displayName	string	Human-readable title shown in the Marketplace
shortDescription	string	Concise subtitle used in compact views
longDescription	string	Detailed description for the details page
developerName	string	Publisher’s display name (e.g., "OpenAI")
category	string	Marketplace bucket (e.g., "Productivity")
capabilities	array[string]	List of capabilities (e.g., ["Interactive","Write"])
websiteURL	string	Public website for the plugin
privacyPolicyURL	string	Link to the privacy policy
termsOfServiceURL	string	Link to the terms of service
defaultPrompt	array[string]	Up to three starter prompts (≤128 characters each)
brandColor	string	Hex color for the plugin card (e.g., #3B82F6)
composerIcon	string	Path to a 64×64 px icon asset
logo	string	Path to a larger logo asset
screenshots	array[string]	PNG files (relative to ./assets/) to showcase the plugin

All asset paths within the interface object must be relative to the plugin root and typically live under an assets/ directory.

Path Conventions and Asset Organization

Paths for skills, hooks, mcpServers, and apps must be relative and start with ./ (e.g., "./skills/"). According to the specification in .agents/skills/plugin-creator/references/plugin-json-spec.md, absolute paths are not permitted.

Asset paths (composerIcon, logo, screenshots) follow the same convention. Place these files in an assets/ folder at your repository root, then reference them as ./assets/filename.png. The screenshots field accepts an array of strings, while defaultPrompt accepts an array of up to three strings, each with a maximum length of 128 characters.

Validation and Testing

When you run the plugin-eval suite, the evaluator performs three critical checks:

1. Presence: Verifies that .codex-plugin/plugin.json exists at the root
2. Syntax: Validates that the file contains valid JSON
3. Schema: Confirms all required top-level and interface fields are present

If any check fails, the evaluator returns a clear remediation message based on the error handling logic in plugins/plugin-eval/src/evaluators/plugin.js. Run npm test in the repository to execute these validations against your manifest.

Complete Code Examples

Full Production Manifest

This example includes all required fields plus recommended optional fields for a complete marketplace listing:

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "Adds AI-powered insights to your workflow",
  "author": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "url": "https://github.com/janedoe"
  },
  "homepage": "https://github.com/janedoe/my-awesome-plugin",
  "repository": "https://github.com/janedoe/my-awesome-plugin",
  "license": "MIT",
  "keywords": ["ai", "insights", "productivity"],
  "skills": "./skills/",
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Awesome Plugin",
    "shortDescription": "AI insights for every task",
    "longDescription": "Leverages OpenAI models to surface actionable insights directly inside your favorite tools.",
    "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 and draft replies for me.",
      "Find open bugs and turn them into Linear tickets."
    ],
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot1.png",
      "./assets/screenshot2.png"
    ]
  }
}

Minimal Valid Manifest

This example contains only the strictly required fields necessary to pass validation:

{
  "name": "minimal-plugin",
  "version": "0.1.0",
  "description": "A minimal Codex plugin",
  "author": {
    "name": "Dev Team",
    "email": "[email protected]",
    "url": "https://github.com/devteam"
  },
  "interface": {
    "displayName": "Minimal Plugin",
    "shortDescription": "Demo only",
    "longDescription": "A placeholder plugin used for testing.",
    "developerName": "OpenAI",
    "category": "Utility",
    "capabilities": ["Write"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": ["Summarize my notes."],
    "brandColor": "#000000",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": []
  }
}

Both examples must be placed at <plugin-root>/.codex-plugin/plugin.json. After saving, run the plugin-eval tests to confirm that your manifest passes validation.

Summary

• Place the manifest at .codex-plugin/plugin.json in your repository root; the loader in plugins/plugin-eval/src/evaluators/plugin.js enforces this exact path.
• Include five top-level fields: name, version, description, author, and interface.
• Populate all thirteen interface sub-fields including displayName, shortDescription, longDescription, developerName, category, capabilities, websiteURL, privacyPolicyURL, termsOfServiceURL, defaultPrompt, brandColor, composerIcon, logo, and screenshots.
• Use relative paths starting with ./ for all assets and external file references.
• Validate with plugin-eval before submission to catch missing fields or syntax errors.

Frequently Asked Questions

What happens if I omit a required field in the interface object?

The plugin-eval validator will return a specific error message indicating which field is missing, referencing the schema defined in .agents/skills/plugin-creator/references/plugin-json-spec.md. The plugin will fail to load until all thirteen interface sub-fields are present, even if the top-level structure is correct.

Can I use absolute paths for assets in the manifest?

No. The specification requires all paths—including composerIcon, logo, screenshots, and references to skills or hooks—to be relative to the plugin root and start with ./. Absolute paths trigger validation errors in the evaluator.

How do I validate my plugin.json before submitting to the marketplace?

Run the plugin-eval test suite using npm test in the repository. This executes the validation logic in plugins/plugin-eval/src/evaluators/plugin.js, which checks for file presence, JSON syntax, and required field completeness. Real-world examples in plugins/zoom/README.md demonstrate typical manifest locations and validation workflows.

Is the skills field required for a basic Codex plugin?

No. While skills, hooks, mcpServers, and apps are recommended for full functionality, they are optional. Only the five top-level fields (name, version, description, author, interface) and the thirteen interface sub-fields are mandatory for a valid manifest.

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