Understanding Plugin-Level Agent Definitions in the OpenAI Plugins Repository

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/<plugin-name>/skills/<skill-name>/agents/openai.yaml

Key files in the repository include:

• plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml
• plugins/zoom/skills/websockets/agents/openai.yaml
• plugins/superpowers/skills/writing-skills/agents/openai.yaml
• plugins/build-macos-apps/skills/window-management/agents/openai.yaml
• plugins/zotero/skills/zotero/agents/openai.yaml

All agent definitions use the filename 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:

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

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/<name>/skills/<skill>/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/<plugin-name>/skills/<skill-name>/agents/openai.yaml. For example, the Zotero skill's agent definition lives at 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, 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.

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