Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/skills/llms.txt

Use this file to discover all available pages before exploring further.

The agents/openai.yaml file provides UI-facing metadata for how a skill appears inside Codex — its display name, description chip, icon, brand color, and the default prompt that activates it. It also declares external tool dependencies, such as MCP server connections that the skill requires. Unlike SKILL.md, this file is read by the Codex harness, not by the agent itself.

​
Top-Level Structure

The file has two top-level keys: interface and dependencies. Both are optional, but at minimum you should provide interface.display_name, interface.short_description, and interface.default_prompt. 
interface:
  display_name: "GH Address Comments"
  short_description: "Address comments in a GitHub PR review"
  icon_small: "./assets/small-400px.png"
  icon_large: "./assets/large-logo.svg"
  brand_color: "#3B82F6"
  default_prompt: "Use $gh-address-comments to address all open review threads on my PR."

dependencies:
  tools:
    - type: "mcp"
      value: "github"
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"
Quoting rules:
  • All string values must be quoted.
  • All keys must be unquoted.

​
interface Fields

​
interface.display_name
string
Human-facing title shown in Codex UI skill lists and chips. Generated automatically from the skill name if not provided (e.g., gh-address-comments → "GH Address Comments"). Use proper casing; well-known acronyms are uppercased automatically (GH, API, PDF, PR, MCP, SQL, CI, CLI, LLM, UI, URL).
display_name: "GH Address Comments"
​
interface.short_description
string
Human-facing short blurb for quick scanning in skill lists. Must be 25–64 characters. Write this as a brief noun phrase describing what the skill does.
short_description: "Address comments in a GitHub PR review"
​
interface.icon_small
string
Relative path (from the skill directory) to a small icon asset, typically ~400px square. By convention, place icons in ./assets/.
icon_small: "./assets/small-400px.png"
​
interface.icon_large
string
Relative path to a larger logo asset. Supports PNG and SVG. By convention, place icons in ./assets/.
icon_large: "./assets/large-logo.svg"
​
interface.brand_color
string
Hex color code used for UI accents such as badges and highlights.
brand_color: "#3B82F6"
​
interface.default_prompt
string
A short example prompt (typically one sentence) that is inserted when the user invokes the skill from the UI. Must explicitly reference the skill using $skill-name syntax.
default_prompt: "Use $gh-address-comments to address all open review threads on my PR."

​
dependencies.tools[] Fields

The dependencies.tools array declares external tools the skill relies on. Currently only mcp type is supported.
​
dependencies.tools[].type
string
required
Dependency category. Only "mcp" is supported.
type: "mcp"
​
dependencies.tools[].value
string
required
Identifier of the tool or dependency — typically the MCP server name.
value: "github"
​
dependencies.tools[].description
string
Human-readable explanation of what this dependency is.
description: "GitHub MCP server"
​
dependencies.tools[].transport
string
Connection type when type is mcp. Common values: "streamable_http".
transport: "streamable_http"
​
dependencies.tools[].url
string
MCP server URL when type is mcp.
url: "https://api.githubcopilot.com/mcp/"

​
Full Example

This example is adapted directly from the openai_yaml.md reference in the skill-creator skill: 
interface:
  display_name: "My Skill"
  short_description: "Does something useful and fast"
  icon_small: "./assets/small-400px.png"
  icon_large: "./assets/large-logo.svg"
  brand_color: "#3B82F6"
  default_prompt: "Use $my-skill to complete my task."

dependencies:
  tools:
    - type: "mcp"
      value: "github"
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"

​
Generating and Regenerating openai.yaml

The generate_openai_yaml.py script creates or regenerates the file from command-line arguments. It reads the skill name from SKILL.md frontmatter and accepts interface overrides via --interface key=value: 
# Generate with all three core fields
scripts/generate_openai_yaml.py path/to/my-skill \
  --interface display_name="My Skill" \
  --interface short_description="Does something useful and fast" \
  --interface default_prompt="Use \$my-skill to complete my task."

# Include optional fields
scripts/generate_openai_yaml.py path/to/my-skill \
  --interface display_name="My Skill" \
  --interface short_description="Does something useful and fast" \
  --interface brand_color="#FF5733" \
  --interface default_prompt="Use \$my-skill to complete my task."
The same --interface flags work with init_skill.py during skill initialization: 
scripts/init_skill.py my-skill --path skills/public \
  --interface display_name="My Skill" \
  --interface short_description="Does something useful and fast" \
  --interface default_prompt="Use \$my-skill to complete my task."
Only include icon_small, icon_large, and brand_color when the user explicitly provides those assets or values. The script generates display_name and short_description automatically from the skill name if you do not supply them via --interface.
After editing SKILL.md, validate that agents/openai.yaml still reflects the skill accurately. If the skill’s purpose or name changes, regenerate the file by running generate_openai_yaml.py again.

Build docs developers (and LLMs) love

Get started for freeTalk to us