# Understanding Plugin-Level Agent Definitions in the OpenAI Plugins Repository > Discover plugin-level agent definitions in the OpenAI plugins repository. Learn how YAML config files define AI model invocation of plugin capabilities, including metadata and execution policies. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: deep-dive - Published: 2026-09-12 --- **Plugin-level agent definitions are YAML configuration files that declare how AI models invoke a plugin's capabilities, specifying both human-readable metadata and execution policies.** Each plugin in the openai/plugins repository can declare one or more agents that describe how the model may invoke the plugin's capabilities. These plugin-level agent definitions standardize how capabilities are exposed to AI systems, ensuring consistent behavior across all plugins through structured configuration files stored in version control. ## What Are Plugin-Level Agent Definitions? Plugin-level agent definitions serve as the contract between the AI model and the plugin's functionality. They tell the model what actions are available, when to use them, and what constraints apply during execution. According to the openai/plugins source code, each definition creates a **named agent** that the model can invoke with a structured request, abstracting the underlying implementation details while enforcing safety and permission boundaries. These definitions reside within individual skills, allowing granular control over how specific capabilities are exposed. The runtime parses these YAML files during plugin initialization to build the execution context available to the model. ## File Structure and Location Agent definitions follow a strict directory convention within the repository structure: ``` plugins//skills//agents/openai.yaml ``` Key files in the repository include: - [`plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml) - [`plugins/zoom/skills/websockets/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/websockets/agents/openai.yaml) - [`plugins/superpowers/skills/writing-skills/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/writing-skills/agents/openai.yaml) - [`plugins/build-macos-apps/skills/window-management/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/build-macos-apps/skills/window-management/agents/openai.yaml) - [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml) All agent definitions use the filename [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) and reside in the `agents/` subdirectory of their respective skill folders. ## Anatomy of an Agent Definition YAML File An agent definition contains two mandatory sections and several optional fields that configure the agent's behavior. ### The Interface Section The `interface` block provides **human-readable metadata** that the model uses to understand when and how to invoke the agent. This section contains: - **`display_name`**: The human-readable name of the agent (e.g., "Zoom Apps SDK") - **`short_description`**: A brief explanation of when to use the agent - **`long_description`** (optional): Detailed guidance on capabilities and use cases The model sees this metadata during context window construction, making it critical for accurate agent selection. ### The Policy Section The `policy` block defines **execution rules and constraints** that govern how the agent operates: - **`allow_implicit_invocation`**: A boolean flag determining whether the model can call the agent automatically without explicit user confirmation - **Permissions**: Required authorization scopes or capabilities - **Rate limits and safety constraints**: Throttling rules and guardrails When `allow_implicit_invocation` is set to `false`, the system requires explicit user approval before executing the agent's actions. ### Optional Configuration Fields Advanced agent definitions may include additional contextual fields: - **`environment_variables`**: Lists required secrets or configuration values (e.g., API tokens) with descriptions - **`examples`**: Sample invocations demonstrating proper usage patterns - **`metadata`**: Arbitrary key-value pairs for runtime or model context ## Real-World Examples from the Repository The Zoom Apps SDK skill provides a minimal agent definition: ```yaml # Source: plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml interface: display_name: Zoom Apps SDK short_description: Use when using Apps SDK. policy: allow_implicit_invocation: false ``` A more comprehensive hypothetical example illustrates advanced configuration: ```yaml interface: display_name: Shopify Storefront GraphQL short_description: Query Shopify storefront data. long_description: | Allows the model to fetch product listings, collections, and checkout information via Shopify's Storefront GraphQL API. policy: allow_implicit_invocation: true environment_variables: - name: SHOPIFY_STOREFRONT_TOKEN description: Private token for authenticating GraphQL requests. ``` ## How the Runtime Uses Agent Definitions The plugin runtime reads agent definition YAML files during the initialization phase to expose named agents to the model. When processing a user request, the model references the **interface** metadata to determine which agent can fulfill the task, then checks the **policy** constraints to verify execution permissions. This architecture ensures that plugin-level agent definitions act as both documentation and enforceable policy. By standardizing this structure in the openai/plugins repository, every plugin exposes safe, well-documented capabilities that the model can reliably invoke while maintaining strict boundaries around implicit actions and required permissions. ## Summary - Plugin-level agent definitions are YAML files stored in `plugins//skills//agents/openai.yaml` that declare available AI agents. - Each definition requires an `interface` section (metadata for the model) and a `policy` section (execution constraints). - The `allow_implicit_invocation` policy flag controls whether the model can execute the agent automatically or requires explicit user confirmation. - Optional fields like `environment_variables` and `examples` provide additional context for complex integrations. - The runtime parses these definitions to create structured, named agents that maintain consistent security and behavior across the plugin ecosystem. ## Frequently Asked Questions ### Where exactly are plugin-level agent definitions stored? Plugin-level agent definitions are stored as YAML files in the `agents/` subdirectory of each skill, specifically at `plugins//skills//agents/openai.yaml`. For example, the Zotero skill's agent definition lives at [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml) according to the openai/plugins repository structure. ### What is the difference between interface and policy in agent definitions? The `interface` section contains human-readable metadata like `display_name` and `short_description` that helps the model understand what the agent does and when to use it. The `policy` section contains execution rules such as `allow_implicit_invocation`, permissions, and safety constraints that control how the agent runs and what restrictions apply during invocation. ### Can a single plugin skill define multiple agents? Yes, the repository structure supports declaring **one or more agents** per skill. While the provided examples show single agents per skill using [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml), the architecture allows multiple YAML files in the `agents/` directory or multiple agent declarations within a single file, enabling granular capability segmentation within a single plugin. ### How does the allow_implicit_invocation policy work? When `allow_implicit_invocation` is set to `true` in the policy section, the model may invoke the agent automatically as part of its reasoning chain without asking the user for explicit confirmation. When set to `false`, the system requires explicit user approval before executing the agent's actions, providing an additional safety layer for sensitive operations.