codex-marketplace-json-valid

.agents/plugins/marketplace.json must be valid JSON with required fields

Severity	error (auto)
Autofix	-
Since	v0.18.0
Repo Types	codex-marketplace
Category	OpenAI Codex

Why

.agents/plugins/marketplace.json is the catalog Codex reads to list and install plugins. When an entry is malformed Codex "skips that plugin entry instead of failing the whole marketplace", so a broken entry is invisible at runtime — the plugin simply never appears.

This rule validates the Codex schema only. .claude-plugin/marketplace.json is a different schema and stays with claude-marketplace-json-valid.

Examples

Bad:

{
  "plugins": [
    {
      "name": "note_taker",
      "source": {"source": "local", "path": "../outside"},
      "policy": {"installation": "MAYBE"}
    }
  ]
}

Good:

{
  "name": "example-codex-plugins",
  "interface": {"displayName": "Example Codex Plugins"},
  "plugins": [
    {
      "name": "note-taker",
      "source": {"source": "local", "path": "./plugins/note-taker"},
      "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
      "category": "Productivity"
    }
  ]
}

How to fix

Add the missing field or correct the value the violation names.

The catalog needs a top-level name and a plugins array. Every entry needs a unique name and a source. A source is either a bare relative path string or an object whose source field selects the type — local (needs path), url (needs url), git-subdir (needs url and path), or npm (needs package). An unrecognized source type is reported as a warning so a type added upstream never breaks an existing marketplace.

Local paths resolve against the marketplace root — the repository root, not .agents/plugins/. They must stay inside that root: an absolute path or one containing .. is an error, and a missing ./ prefix is informational. An npm registry must be an HTTPS URL with no embedded credentials, query string, or fragment.

The spec asks for policy.installation, policy.authentication, and category on every entry, so their absence is a warning. Unrecognized policy values are warnings too: the upstream sources disagree on strictness — the prose spec offers the values as examples ("such as"), while the field-level plugin-json-spec.md publishes closed enums — and a warning is the safe intersection of the two. Use installation-values and authentication-values to adjust the sets.

Configuration

rules:
  codex-marketplace-json-valid:
    enabled: auto  # true | false | auto
    severity: error

Parameter	Description	Default
installation-values	Recognized policy.installation values	["AVAILABLE", "INSTALLED_BY_DEFAULT", "NOT_AVAILABLE"]
authentication-values	Recognized policy.authentication values	["ON_INSTALL", "ON_USE"]

Run skillsaw explain codex-marketplace-json-valid to see this documentation and the rule's effective configuration in your terminal.