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 | Not established | string | Human-readable explanation of the dependency. | |
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. |