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

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 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 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:

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, this file provides UI metadata that helps users understand when to use the Slack integration:

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 and referenced in the package README, this configuration ensures the skill only executes when explicitly requested:

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 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:

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 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.

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