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

> Discover the role of agents/openai.yaml files in OpenAI plugins. This crucial file defines skill discovery, invocation policy, and LLM prompt construction for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-20

---

**The [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/figma/agents/openai.yaml):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/agents/openai.yaml):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/core/budget.js):

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

```

Once located, the YAML contents are merged into [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) per skill directory. The manifest builder in [`plugins/plugin-eval/src/core/budget.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/core/budget.js) resolves a single path ([`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) relative to the skill root. For example, the Figma skill places it at [`plugins/figma/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/figma/agents/openai.yaml), while nested skills like Zoom webhooks use paths such as [`plugins/zoom/skills/webhooks/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/agents/openai.yaml). The `plugin-eval` core dynamically constructs this path using Node.js `path.join` operations.