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

> Learn to create a Codex plugin manifest file plugin.json with all required fields. Ensure your plugin is correctly configured for seamless integration and discoverability.

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

---

**To create a valid Codex plugin manifest, place a [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) (lines 13-28). The loader specifically checks for the existence of [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "Adds AI-powered insights to your workflow",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "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:

```json
{
  "name": "minimal-plugin",
  "version": "0.1.0",
  "description": "A minimal Codex plugin",
  "author": {
    "name": "Dev Team",
    "email": "dev@example.com",
    "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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) in your repository root; the loader in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.