agents/openai.yaml sits next to a skill's SKILL.md and tells Codex how to show the skill, when it may be used, and what it depends on. Only Codex documents this file. Quote all string values. Keep mapping keys unquoted.
| Field | Required | Type | What it does | Limits |
|---|---|---|---|---|
| How the skill appears | ||||
interface.display_name | Optional | string | Human-facing title shown in UI skill lists and chips. | |
interface.short_description | Optional | string | Human-facing short UI blurb for quick scanning. | Length is 25 through 64 characters, inclusive. |
interface.icon_small | Optional | string | Path to a small icon asset relative to the skill directory. | Default location is the skill's ./assets/ directory. |
interface.icon_large | Optional | string | Path to a larger logo asset relative to the skill directory. | Default location is the skill's ./assets/ directory. |
interface.brand_color | Optional | string | Hex color used for UI accents such as badges. | Value is a hexadecimal color string. |
interface.default_prompt | Optional | string | Default prompt snippet inserted when invoking the skill. | Use a helpful, short example, typically one sentence. The prompt must explicitly mention the skill using $skill-name syntax. |
| What it needs | ||||
dependencies.tools | Optional | array<object> | Tool dependencies advertised by the skill. | Dependencies are declarations, not permission boundaries. |
dependencies.tools[].type | Required | string | Dependency category. | Only mcp is currently documented as supported. The loader drops a dependency item when this field is absent, empty, or longer than 64 characters. |
dependencies.tools[].value | Required | string | Identifier of the tool or dependency. from source | The loader drops a dependency item when this field is absent, empty, or longer than 1024 characters. |
dependencies.tools[].description | Optional | string | Human-readable explanation of the dependency. from source | Released 0.162.1 deserializes this field as Option<String> and resolves it without requiring a value. |
dependencies.tools[].transport | Sometimes required | string | Connection type for an MCP dependency. | Applies when dependencies.tools[].type is mcp. |
dependencies.tools[].url | Sometimes required | string | MCP server URL for an MCP dependency. | Applies when dependencies.tools[].type is mcp. |
dependencies.tools[].command | Optional | string | Command used to launch a tool dependency such as a stdio MCP server. from source | The loader normalizes whitespace and ignores an empty value or one longer than 1024 characters. |
dependencies.tools[].oauth.callbackPort | Optional | integer | OAuth callback port for the dependency. from source | The value is parsed as an unsigned 16-bit integer. callback_port is accepted as an alias for callbackPort. |
| When it can be used | ||||
policy.allow_implicit_invocation | Optional | boolean | Whether the model may select the skill without the user naming it explicitly. | False excludes the skill from the model-visible implicit skill catalog while explicit $skill invocation remains available. The field defaults to true when the policy or value is absent. |
policy.products | Optional | array<string> | Restricts the skill metadata to matching OpenAI products. from source | An empty list means no product restriction. The loader parses values through the Codex Product vocabulary. |
Notes and sources
Codex CLI
- This product-specific file is read by the machine or harness, not as agent instructions; SKILL.md frontmatter is modeled separately.
- Codex source confirms that allow_implicit_invocation defaults to true and controls admission to the model-visible implicit skill catalog; it does not disable explicit $skill invocation.
- Malformed or unreadable optional metadata fails open: Codex ignores agents/openai.yaml metadata and continues loading SKILL.md.
- Serde does not deny unknown fields in the loader structs, so unknown mapping keys are ignored by the observed implementation.
- The source accepts command, OAuth callback-port, and product-policy fields that are not all present in the bundled full-field reference; their evidence status remains first-party-source.
- Source-observed in Codex 0.160.1 (d27764b82f7118f674371e6d6e76271d9d606edb): false removes the skill name, description and path before initial listing budget allocation; explicit invocation still loads instructions into conversation context outside that budget.
- Released 0.162.1 metadata structs and resolver rechecked on October 15; dependency description is optional in the loader. Historical policy evidence remains separately dated.
- Codex skills documentation
- Codex bundled openai.yaml field reference, Documentation, checked 2026-08-31
- Codex openai.yaml metadata loader, Source code, checked 2026-08-31
- Codex skill invocation policy model, Source code, checked 2026-08-31
- OpenAI plugin openai.yaml invocation-policy example, Source code, checked 2026-08-31
- Codex: Agent Skills, Documentation, checked 2026-08-27
- Codex 0.160.1 host skill policy visibility, Source code, checked 2026-10-08
- Codex 0.160.1 executor skill policy visibility, Source code, checked 2026-10-08
- Codex 0.160.1 visible catalog filtering before budgeting, Source code, checked 2026-10-08
- Released Codex 0.162.1 optional metadata fields, Source code, checked 2026-10-15
- Released Codex 0.162.1 full metadata reference, Documentation, checked 2026-10-15
- Codex 0.162.1 skill renderer, Source code, checked 2026-10-15
- Codex 0.162.1 approximate byte accounting, Source code, checked 2026-10-15
- Codex 0.162.1 host skill policy visibility, Source code, checked 2026-10-15
- Codex 0.162.1 executor skill policy visibility, Source code, checked 2026-10-15
- Codex 0.162.1 visible catalog filtering before budgeting, Source code, checked 2026-10-15