How to Add Custom Agents to a Plugin Using openai.yaml

You add custom agents to an OpenAI plugin by placing an openai.yaml file inside a skill's agents/ folder, which exposes the agent's UI metadata and optional invocation policies to the OpenAI platform.

The openai.yaml configuration file serves as the entry point for defining custom agents in the openai/plugins repository. Each agent represents a skill entry-point that the OpenAI platform can invoke through the ChatGPT interface or API. By placing this file in the correct directory structure, the plugin automatically registers the agent without requiring manual updates to the manifest.

Understanding the openai.yaml Structure

The openai.yaml file contains two primary sections: interface for UI metadata and an optional policy block for runtime behavior controls.

The Interface Section

The interface section provides human-readable metadata that appears in the OpenAI Plugin Marketplace and the ChatGPT UI. According to the source code in plugins/zotero/skills/zotero/agents/openai.yaml, this section requires:

• display_name: The human-readable name shown in the marketplace
• short_description: A brief tagline explaining the agent's purpose
• icon_small: Relative path to a small icon (PNG or SVG recommended)
• icon_large: Relative path to a larger icon for detailed views
• default_prompt: Instructions that define the agent's behavior and capabilities

The Policy Section (Optional)

The optional policy section controls how the OpenAI runtime invokes the agent. This block is defined in the same openai.yaml file and governs cost management and invocation methods.

Key policy fields include:

• allow_implicit_invocation: When set to true, the model can automatically select this agent based on user requests; when false, users must explicitly invoke it via tool calls
• explicit_only_invoke_cost_tokens: Sets an upper bound on token costs for explicit-only invocations
• estimated_static_policy_aware: When true, treats the agent as static for budgeting purposes, preventing inflation of implicit-invocation scores
• max_concurrency: (Advanced) Limits the number of parallel executions allowed

Step-by-Step Implementation Guide

Follow these steps to add custom agents to your plugin:

1. Create the directory structure inside your skill folder:

   plugins/<your-plugin>/skills/<skill-name>/agents/

2. Create the openai.yaml file in the agents/ directory with your metadata:

   interface:
     display_name: "My Awesome Agent"
     short_description: "Brief tagline for the agent"
     icon_small: "./assets/icon-small.png"
     icon_large: "./assets/icon.png"
     default_prompt: "You are My Awesome Agent. Help users accomplish specific tasks."
   
   policy:
     allow_implicit_invocation: false
     explicit_only_invoke_cost_tokens: 1000

3. Provide asset files referenced by icon_small and icon_large in the same directory or a subfolder like ./assets/.

4. Commit your changes. The repository's CI pipeline automatically validates the openai.yaml syntax against the OpenAI specification.

5. Verify in the marketplace. After deployment, the new agent appears under the plugin's Agents tab in the OpenAI Plugin Store.

Configuring Agent Invocation Policies

Policy configuration allows fine-grained control over when and how your agent executes. In plugins/zotero/skills/zotero/agents/openai.yaml and similar implementations, these settings prevent unauthorized implicit invocations and manage computational costs.

Use allow_implicit_invocation: false when your agent performs expensive operations like code generation or database queries. This forces users to explicitly request the agent rather than having the model select it automatically.

Set explicit_only_invoke_cost_tokens to cap token consumption for safety-critical or resource-intensive agents. For example, a SQL generator agent might limit costs to 2000 tokens:

policy:
  allow_implicit_invocation: false
  explicit_only_invoke_cost_tokens: 2000
  estimated_static_policy_aware: true

Complete File Structure Example

Here is the complete directory layout for a plugin with custom agents, based on the repository structure at openai/plugins:

plugins/
└─ my-plugin/
   ├─ skills/
   │  └─ sql-gen/
   │     ├─ agents/
   │     │  └─ openai.yaml        ← Metadata & policy configuration
   │     ├─ references/
   │     └─ SKILL.md
   └─ .codex-plugin/
      └─ plugin.json               ← Automatically discovers agents

The .codex-plugin/plugin.json file (as seen in plugins/github/.codex-plugin/plugin.json) automatically picks up agents by scanning the agents/ directory for openai.yaml files. No manual registration entries are required.

Minimal Configuration Example

For a lightweight implementation similar to the Zotero plugin, use this minimal openai.yaml:

interface:
  display_name: "Zotero"
  short_description: "Search Zotero and add citations"
  icon_small: "./assets/icon.png"
  icon_large: "./assets/icon.png"
  default_prompt: "Use $Zotero to search my Zotero library, export BibTeX, and add citations to my draft."

Summary

• Place openai.yaml in the agents/ folder of your skill directory to register custom agents automatically.
• Define the interface section with display_name, short_description, icons, and default_prompt for marketplace visibility.
• Add optional policy controls using allow_implicit_invocation and explicit_only_invoke_cost_tokens to manage invocation behavior and costs.
• Reference files correctly via relative paths for assets, and ensure the .codex-plugin/plugin.json exists in your plugin root.
• Commit and push to trigger automatic validation and marketplace updates.

Frequently Asked Questions

Where do I place the openai.yaml file when adding custom agents?

Place the openai.yaml file inside the agents/ subdirectory of your specific skill folder, following the pattern plugins/<plugin-name>/skills/<skill-name>/agents/openai.yaml. The OpenAI platform scans this directory automatically to discover available agents.

Is the policy section required in openai.yaml?

No, the policy section is optional. If omitted, the agent uses default invocation settings. However, for agents that perform expensive operations or require explicit user consent, adding allow_implicit_invocation: false is strongly recommended to prevent automatic selection by the model.

How does the plugin manifest discover new agents?

The .codex-plugin/plugin.json file automatically discovers agents by scanning the agents/ directory for any openai.yaml files. As implemented in the openai/plugins repository, you do not need to manually update the manifest or add registry entries when creating new agent configurations.

What image formats are supported for agent icons?

The icon_small and icon_large fields in openai.yaml support standard web image formats including PNG and SVG. Place these assets in the same directory as your openai.yaml file or in a subfolder (commonly ./assets/) and reference them using relative paths.

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