# What Are Agent YAML Files and How Are They Used in OpenAI Plugins?

> Discover agent YAML files in OpenAI plugins. Learn how these config files define skill interfaces and invocation policies for better UI metadata and skill control.

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

---

**TLDR**: Agent YAML files are declarative configuration files that define the OpenAI-specific interface and invocation policies for each skill in a plugin, enabling the platform to display UI metadata and control whether skills can be called implicitly or explicitly.

Agent YAML files serve as the declarative bridge between raw skill implementations and the OpenAI platform's discovery layer in the **openai/plugins** repository. These files reside alongside each skill and contain the metadata required for the OpenAI runtime to surface capabilities to users and enforce invocation rules. Every skill directory contains an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file that the build system consumes during packaging to generate the final plugin manifest.

## The Structure of Agent YAML Files

Agent YAML files contain two primary sections that control how a skill appears and behaves within the OpenAI ecosystem.

### Interface Section (UI Metadata)

The `interface` block defines human-readable metadata that the OpenAI platform displays to users. This includes the skill's name, description, visual branding, and default prompt template.

Key fields in the `interface` section include:

- `display_name`: The human-readable name shown in the UI
- `short_description`: A brief explanation of what the skill does
- `icon_small` and `icon_large`: Paths to icon assets for different contexts
- `brand_color`: Hex color code for visual consistency
- `default_prompt`: Template text suggesting how users might invoke the skill

### Policy Section (Invocation Rules)

The `policy` block controls **invocation rules** that determine whether the skill can be called automatically by the model or only when explicitly mentioned by the user. The `allow_implicit_invocation` boolean flag governs this behavior.

When `allow_implicit_invocation: false`, the skill becomes *explicit-only*, meaning the model will only invoke it when the user directly mentions the skill by name. This setting is critical for sensitive operations or webhook configurations where automatic triggering could cause unintended side effects.

## How Agent YAML Files Are Consumed by the Build System

During the plugin packaging process, build scripts walk the repository structure and process every [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file found within skill directories. The following Python pseudo-code illustrates how the OpenAI build tools perform this walk and merge metadata into the plugin manifest:

```python
import os, yaml, json

def collect_agent_metadata(root):
    manifest = {}
    for dirpath, _, filenames in os.walk(root):
        if "agents/openai.yaml" in filenames:
            with open(os.path.join(dirpath, "agents/openai.yaml")) as f:
                data = yaml.safe_load(f)
            skill_id = os.path.relpath(dirpath, root)   # e.g. “skills/slack”

            manifest[skill_id] = data
    return manifest

# When packaging the plugin:

metadata = collect_agent_metadata("plugins/my-plugin")
with open("manifest.json", "w") as out:
    json.dump(metadata, out, indent=2)

```

The real OpenAI build tools perform the same recursive walk, merging each `interface` block into the skill-list UI and applying `policy` restrictions when creating the skill-registry entries that the runtime uses to discover and invoke skills.

## Real-World Examples from the OpenAI Plugins Repository

### Slack Skill Configuration

The Slack skill in the openai/plugins repository demonstrates a complete interface definition. Located at [`plugins/slack/skills/slack/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/slack/skills/slack/agents/openai.yaml), this file provides UI metadata that helps users understand when to use the Slack integration:

```yaml
interface:
  display_name: "Slack"
  short_description: "Summarize threads and draft posts"
  icon_small: "./assets/slack-small.svg"
  icon_large: "./assets/slack.png"
  brand_color: "#611F69"
  default_prompt: "Use $slack to summarize a thread and draft a Slack‑ready reply or update."

```

### Zoom Webhook Explicit-Only Policy

The Zoom webhook skill uses the `policy` section to restrict invocation behavior. As documented in [`plugins/zoom/skills/webhooks/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/agents/openai.yaml) and referenced in the package README, this configuration ensures the skill only executes when explicitly requested:

```yaml
interface:
  display_name: Setup Zoom Webhooks
  short_description: Use when building Zoom webhooks.
policy:
  allow_implicit_invocation: false

```

According to the Zoom plugin README, every bundled skill carries an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file to control this **explicit-only** behavior. The same pattern appears across other plugin families including Notion and Figma, where the YAML is described as being "wired into the manifest" according to the Notion README documentation.

## Creating Your Own Agent YAML File

To implement an agent YAML file for a new skill in your plugin, create a file at `plugins/<plugin-name>/skills/<skill-name>/agents/openai.yaml` with the following structure:

```yaml
interface:
  display_name: "My Awesome Tool"
  short_description: "Does something useful"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#123456"
  default_prompt: "Use $mytool to …"

policy:
  allow_implicit_invocation: true   # optional – defaults to true

```

The build process automatically discovers this file when packaging your plugin, merging the metadata into the generated manifest that the OpenAI platform consumes at runtime.

## Summary

- Agent YAML files live at [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) within each skill directory and define the OpenAI-specific surface for that skill.
- The `interface` section controls UI presentation including display names, descriptions, icons, and brand colors.
- The `policy` section governs invocation behavior through the `allow_implicit_invocation` flag, enabling restriction to explicit-only usage when set to `false`.
- Build scripts consume these files during packaging to generate the plugin manifest, registering skills with the appropriate metadata and security policies.
- Real-world implementations in the openai/plugins repository demonstrate these patterns across Slack, Zoom, Notion, and other integrations.

## Frequently Asked Questions

### What is the difference between interface and policy in agent YAML files?

The `interface` section defines **presentation-layer metadata** such as display names, descriptions, icons, and default prompts that help users understand and discover the skill. The `policy` section defines **execution constraints**, specifically controlling whether the model can invoke the skill automatically (implicit invocation) or only when explicitly mentioned by the user (explicit invocation).

### Where should I place the agents/openai.yaml file in my plugin?

Place the file at `plugins/<plugin-name>/skills/<skill-name>/agents/openai.yaml`, where `<skill-name>` represents the specific capability directory. This location allows the build scripts to correctly associate the YAML configuration with the corresponding skill implementation during the manifest generation process.

### Can I allow both implicit and explicit invocation for the same skill?

Yes, by setting `allow_implicit_invocation: true` (or omitting the policy section, since true is the default), the skill remains available for both implicit and explicit invocation. The model may automatically invoke the skill when contextually appropriate, or users can directly reference it by name for specific operations.

### How does the OpenAI platform use the brand_color and icon fields?

The OpenAI platform consumes these fields from the `interface` section to render consistent visual branding in the plugin marketplace and chat interface. The `brand_color` provides hex color values for UI theming, while `icon_small` and `icon_large` reference asset paths that display alongside the skill name, creating visual recognition and trust indicators for users interacting with your plugin.