What Is the Role of agents/openai.yaml Files in Plugin Skill Directories?

The agents/openai.yaml file serves as the declarative contract that bridges a skill's internal implementation with the OpenAI surface, controlling discovery, invocation policy, and LLM prompt construction.

In the openai/plugins repository, each skill directory includes an agents/openai.yaml configuration that defines how Codex (the LLM assistant) exposes that capability to users. This YAML file provides the metadata, display properties, and runtime policies required for the skill to integrate with the OpenAI platform.

Interface Metadata and Skill Discovery

The primary function of agents/openai.yaml is to supply interface metadata that renders the skill discoverable and usable. This includes human-readable identifiers and visual assets that appear in the Codex UI.

Key fields include:

• display_name: The user-facing label for the skill.
• short_description: A concise explanation of the capability.
• default_prompt: System instructions injected into the LLM context when the skill activates.
• Icon references: Visual assets for UI chips and menus.

For example, the Figma skill defines its surface in plugins/figma/agents/openai.yaml:

display_name: "Figma"
short_description: "Design and prototype interfaces collaboratively"

This metadata allows Codex to generate UI chips and construct the prompt context when users interact with the Figma integration.

Invocation Policy Controls

Beyond metadata, agents/openai.yaml governs how the skill may be triggered through the policy block, specifically the allow_implicit_invocation boolean.

When allow_implicit_invocation is set to true, the LLM may automatically select the skill based on natural language intent. When set to false, the skill becomes explicit-only, requiring the user to invoke it with $skill-name syntax.

The Zoom webhook skill demonstrates this restriction in plugins/zoom/skills/webhooks/agents/openai.yaml:

policy:
  allow_implicit_invocation: false

This configuration ensures that sensitive webhook operations are never triggered accidentally by generic task wording, enforcing strict explicit invocation requirements.

Integration with the Plugin Manifest

During the build process, agents/openai.yaml is automatically consumed and injected into the plugin's manifest. The plugin-eval core resolves the file using path construction logic found in plugins/plugin-eval/src/core/budget.js:

const policyPath = path.join(rootPath, "agents", "openai.yaml");

Once located, the YAML contents are merged into .codex-plugin/plugin.json under the agents section. This makes the skill discoverable to the OpenAI platform runtime and ensures that metadata and policies are synchronized across the plugin ecosystem.

Runtime Behavior and Prompt Construction

At runtime, Codex performs the following sequence when loading a plugin:

1. Scans for agents/openai.yaml files within skill directories to build the capability index.
2. Renders UI elements using the display_name and short_description fields.
3. Constructs the LLM prompt by appending the default_prompt content when the skill is invoked.
4. Enforces invocation policies by checking allow_implicit_invocation before permitting automatic skill selection.

This declarative approach allows developers to modify skill behavior without touching implementation code, simply by updating the YAML configuration.

Summary

• agents/openai.yaml files act as the canonical contract between skill implementations and the OpenAI platform in the openai/plugins repository.
• Interface metadata (display_name, short_description, default_prompt) drives UI rendering and LLM context construction.
• Invocation policies (allow_implicit_invocation) control whether skills are triggered automatically by intent or require explicit $skill-name calls.
• Manifest integration occurs via plugin-eval path resolution (path.join(rootPath, "agents", "openai.yaml")) and results in injection into .codex-plugin/plugin.json.

Frequently Asked Questions

What happens if an agents/openai.yaml file is missing from a skill directory?

Without an agents/openai.yaml file, the skill remains invisible to the Codex discovery mechanism. The plugin-eval build process specifically looks for this file at path.join(rootPath, "agents", "openai.yaml"), and its absence prevents the skill from being registered in the plugin manifest, effectively disabling the capability.

How does the allow_implicit_invocation policy affect user interaction?

When allow_implicit_invocation is set to true, the LLM can automatically route user requests to the skill based on natural language patterns. When set to false as seen in plugins/zoom/skills/webhooks/agents/openai.yaml, users must specifically reference the skill with $skill-name notation, preventing accidental invocations of sensitive operations.

Can multiple YAML files define different agent configurations for the same skill?

No. The OpenAI plugin architecture expects exactly one agents/openai.yaml per skill directory. The manifest builder in plugins/plugin-eval/src/core/budget.js resolves a single path (agents/openai.yaml), and multiple configurations would require separate skill directories to maintain distinct agent identities.

Where is the agents/openai.yaml file located within the repository structure?

The file resides at agents/openai.yaml relative to the skill root. For example, the Figma skill places it at plugins/figma/agents/openai.yaml, while nested skills like Zoom webhooks use paths such as plugins/zoom/skills/webhooks/agents/openai.yaml. The plugin-eval core dynamically constructs this path using Node.js path.join operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}