codex-openai-metadata

Validate skill openai.yaml and catalog-compatible plugin metadata

Severity	error (auto)
Autofix	-
Since	v0.18.0
Repo Types	agent-plugin, agentskills, codex-marketplace, codex-plugin, dot-claude, marketplace, single-plugin
Category	OpenAI Codex

Why

The codex- prefix names the convention's origin, not a repository type: agents/openai.yaml is OpenAI's skill-metadata file, and this rule validates it wherever it appears — including skills in Claude or plain Agent Skills repositories that also publish to the OpenAI catalog.

OpenAI documents agents/openai.yaml as optional skill metadata for UI labels, icons, invocation policy, and tool dependencies. The OpenAI plugin catalog also contains plugin-root files in this form, which skillsaw supports as an observed compatibility convention. Published plugin presentation metadata is otherwise defined in .codex-plugin/plugin.json. Invalid YAML or dangling asset paths can make the associated skill or catalog-compatible plugin render incorrectly.

Examples

Bad:

interface:
  icon_small: /tmp/icon.svg
policy:
  allow_implicit_invocation: "yes"

Good:

interface:
  display_name: Research Router
  short_description: Route a research request to the right workflow
  icon_small: ./assets/router.svg
  brand_color: "#0F6CBD"
  default_prompt: Help me plan this research task.
policy:
  allow_implicit_invocation: true

How to fix

Resolve skill metadata paths from the skill root. For the observed plugin-root compatibility form, resolve them from the plugin root. Bundle referenced icons inside the owning skill or plugin. Use mappings for interface, policy, and dependencies; policy.allow_implicit_invocation must be a boolean. interface.brand_color must be a six-hex-digit #RRGGBB color — no shorthand, no CSS keywords — the format OpenAI's bundled plugin validator enforces.

See OpenAI's documentation on optional skill metadata and, for the documented plugin metadata surface, on plugin structure.

Configuration

rules:
  codex-openai-metadata:
    enabled: auto  # true | false | auto
    severity: error

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