Guide · updated Oct 27, 2026

How to validate plugin.json

Codex is pretty quiet when a manifest is wrong. The plugin just doesn't show up. Here's what it actually needs and the stuff that trips people up.

The quick way

Paste it into our free plugin.json validator. It runs in your browser and flags errors, warnings and nice-to-haves. It also checks marketplace.json.

What it needs

name: kebab-case (my-plugin, not My Plugin). It's the id.
version: semver like 0.1.0.
description: one clear sentence.
The file sits at .codex-plugin/plugin.json. Only that file goes in that folder. Skills, .mcp.json and hooks live at the plugin root.

The mistakes we see most

Paths that don't start with ./, or absolute paths like /Users/me/....
Paths with .. that point outside the plugin.
Marketplace entries missing source or policy.
Secrets pasted into the manifest. Use env vars instead.

Questions people ask

Is there an official plugin.json schema?

OpenAI documents the fields in its plugin build docs, and many manifests reference the agent-plugins.org schema in $schema. Our validator checks the commonly documented rules.

Does the validator upload my file?

No. It's plain JavaScript in the page, nothing is sent anywhere.

All guides · Free tools · FAQ · Browse all 346 plugins