<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# 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, antigravity-plugin, codex-marketplace, codex-plugin, dot-claude, grok-marketplace, grok-plugin, marketplace, single-plugin |
| **Category** | [OpenAI Codex](codex.md) |

## 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:**

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

**Good:**

```yaml
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](https://learn.chatgpt.com/docs/build-skills#optional-metadata)
and, for the documented plugin metadata surface, on
[plugin structure](https://developers.openai.com/plugins/build/plugins#plugin-structure).

## Configuration

```yaml
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.*