How to Organize Plugin Categories in the OpenAI Plugins Manifest

Set the category field inside the interface object of your plugin.json manifest to a title-cased string from the established taxonomy—such as "Productivity" or "Developer Tools"—to control how your plugin appears in the Codex UI catalog.

Organizing plugin categories in the manifest ensures your OpenAI plugin surfaces correctly in the Codex catalog. In the openai/plugins repository, every plugin defines its classification through a single metadata field located in the *.codex-plugin/plugin.json file. This field determines how users filter and discover tools in the plugin marketplace.

Where the Category Field Lives

The category property is nested inside the interface object of the manifest. According to the source code structure in openai/plugins, each plugin directory contains a hidden .codex-plugin folder housing the plugin.json configuration.

{
  "interface": {
    "displayName": "Zoom",
    "category": "Productivity",
    "shortDescription": "Video conferencing",
    "longDescription": "...",
    "developerName": "Zoom"
  }
}

The value must be a single string; arrays or multiple categories are not supported by the schema.

Established Category Taxonomy

The repository maintains a controlled vocabulary to ensure consistent grouping in the UI. Choose from the following title-cased categories based on your plugin's primary function:

• Productivity – Office automation, calendars, and communication (e.g., Zoom, Slack)
• Developer Tools – Code generation, debugging, and CI/CD pipelines (e.g., Sentry)
• Research – Scientific data, analysis pipelines, and academic APIs (e.g., Zotero)
• Design – Visual assets, image libraries, and creative utilities (e.g., Shutterstock)
• Corporate Finance – Accounting, invoicing, and financial tracking (e.g., QuickBooks)
• Engineering, Lifestyle, and Creative Production

Guidelines for Selection

• Match the core use case: Select the category that reflects the most common user scenario, even if the plugin spans multiple domains.
• Use title case: Capitalize the first letter of each word (e.g., "Developer Tools" not "developer tools").
• Avoid special characters: Stick to alphanumeric characters and spaces where appropriate, following the existing taxonomy format.
• Consult maintainers before adding new categories: The taxonomy is intentionally limited; propose additions through the repository's issue tracker.

How to Organize Plugin Categories in the Manifest

Update your plugin classification by editing the manifest file directly:

1. Open the manifest located at plugins/{your-plugin}/.codex-plugin/plugin.json.
2. Set the interface.category value to the appropriate title-cased string from the taxonomy.
3. Validate against the schema using the test fixtures in plugins/plugin-eval/fixtures/ to ensure compliance.
4. Commit the change with a descriptive message, such as fix: set category to "Research".

When moving or renaming a plugin, update the category field immediately to prevent the UI from displaying stale metadata.

Real-World Examples from the Repository

These actual implementations in openai/plugins demonstrate correct category organization:

• Zoom (plugins/zoom/.codex-plugin/plugin.json): "Productivity"
• Slack (plugins/slack/.codex-plugin/plugin.json): "Productivity"
• Zotero (plugins/zotero/.codex-plugin/plugin.json): "Research"
• Sentry (plugins/sentry/.codex-plugin/plugin.json): "Developer Tools"
• Shutterstock (plugins/shutterstock/.codex-plugin/plugin.json): "Design"
• QuickBooks (plugins/quickbooks/.codex-plugin/plugin.json): "Corporate Finance"

Summary

• Organize plugin categories in the manifest by setting the interface.category field in plugins/{name}/.codex-plugin/plugin.json.
• Use title-cased strings from the established taxonomy (e.g., "Productivity", "Developer Tools").
• The schema supports only a single category per plugin; choose the primary use case when domains overlap.
• Validate changes using fixtures in plugins/plugin-eval/fixtures/ before submitting pull requests.
• Update the manifest directly when refactoring plugins to keep the Codex catalog and documentation synchronized.

Frequently Asked Questions

Can I assign multiple categories to a single plugin?

No. The manifest schema only accepts a single string for the category field. If your plugin spans multiple domains, select the category that best represents the most common user scenario according to the openai/plugins source code.

What happens if I use a category not in the established taxonomy?

The Codex UI may fail to surface your plugin correctly or filter it alongside unrelated tools. New categories should be proposed to the maintainers before being added to the manifest to ensure consistency across the ecosystem.

Is the category field case-sensitive?

While JSON strings are technically case-sensitive, the repository convention requires title case (e.g., "Developer Tools" not "developer tools"). Consistent formatting ensures proper catalog filtering and grouping in the Codex interface.

Where can I find examples of valid manifest files?

Reference the test fixtures located in plugins/plugin-eval/fixtures/ or examine existing production plugins such as plugins/zoom/.codex-plugin/plugin.json to see how established categories are implemented in valid manifests.

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