How to Create Agents Within a Plugin Using `agents/openai.yaml`

You create agents within a plugin by placing an openai.yaml file in the skill's agents/ directory, defining the interface metadata and optional policy controls that the OpenAI platform automatically discovers and surfaces in the marketplace.

The OpenAI plugins repository enables developers to extend AI capabilities through modular skills that expose specialized agents. Each agent acts as a skill entry-point that the platform invokes, configured through a single YAML file that supplies both UI metadata for the marketplace and fine-grained invocation policies for the runtime.

Understanding the agents/openai.yaml Structure

The configuration file divides into two primary sections: the required interface block that drives the marketplace UI, and the optional policy block that governs runtime constraints.

The Interface Section

This section supplies human-readable metadata that appears in the OpenAI Plugin Store and ChatGPT UI. According to the canonical Zotero implementation at plugins/zotero/skills/zotero/agents/openai.yaml, valid fields include:

• display_name: The agent's title in the marketplace
• short_description: A brief tagline explaining functionality
• icon_small and icon_large: Relative paths to PNG or SVG asset files
• default_prompt: The system prompt context provided when the agent initializes

The Policy Section (Optional)

When you need fine-grained control over how the model invokes your agent, the policy section specifies runtime constraints. This controls whether the agent can be selected automatically or requires explicit tool calls, among other behaviors.

Step-by-Step Guide to Creating an Agent

Follow these steps to add an agent to your plugin using the agents/openai.yaml configuration method:

1. Create the directory structure. Inside your skill folder, create an agents/ subdirectory:

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

2. Add the configuration file. Create openai.yaml in that directory with the required interface fields:

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

3. Provide visual assets. Place the icon files referenced by icon_small and icon_large in the specified relative paths (typically an assets/ subfolder).

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 your plugin's Agents tab in the OpenAI Plugin Store.

Controlling Agent Invocation with Policy Fields

The optional policy section in agents/openai.yaml lets you enforce specific runtime behaviors. These fields control costs, concurrency, and invocation methods:

• allow_implicit_invocation: Set to false to require explicit tool calls rather than automatic model selection
• explicit_only_invoke_cost_tokens: Integer cap on token costs for explicit-only invocations (e.g., 1000 or 2000)
• estimated_static_policy_aware: When true, treats the agent as static for budgeting purposes, preventing inflation of the implicit-invocation score
• max_concurrency: (Advanced) Limits the number of parallel executions of this agent

Complete Configuration Examples

Minimal Configuration (Zotero Style)

Based on the reference implementation at plugins/zotero/skills/zotero/agents/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."

Advanced Configuration with Policy Controls

For agents requiring strict invocation controls, such as expensive SQL generation tools:

interface:
  display_name: "SQL Generator"
  short_description: "Generate parameterised SQL queries"
  icon_small: "./assets/sql-sm.png"
  icon_large: "./assets/sql.png"
  default_prompt: "You are a SQL generator. ..."

policy:
  allow_implicit_invocation: false
  explicit_only_invoke_cost_tokens: 2000
  estimated_static_policy_aware: true

Directory Structure

The complete layout for a skill with an agent configuration:

plugins/
└─ my-plugin/
   ├─ skills/
   │  └─ sql-gen/
   │     ├─ agents/
   │     │  └─ openai.yaml
   │     ├─ references/
   │     └─ SKILL.md
   └─ .codex-plugin/
      └─ plugin.json

How the Platform Discovers Your Agents

The OpenAI plugin infrastructure implements automatic discovery—no manual registration required. When you place openai.yaml in the agents/ folder, the platform scans this directory during the build process. The plugin manifest at .codex-plugin/plugin.json automatically picks up the agent definition, as demonstrated in the GitHub plugin example at plugins/github/.codex-plugin/plugin.json within the OpenAI plugins repository.

This discovery mechanism means you can add multiple agents to a single plugin by creating separate agents/openai.yaml files in different skill directories, each with independent metadata and policy configurations.

Summary

• Create an agents/ folder inside your skill directory to house the configuration file
• Define the interface section in openai.yaml to control marketplace display names, descriptions, icons, and default prompts
• Add the optional policy section to restrict implicit invocation, set token cost caps, or configure concurrency limits
• Rely on automatic discovery—the platform detects agents/openai.yaml files without manual manifest updates at .codex-plugin/plugin.json
• Validate through CI—the repository automatically checks YAML syntax when you commit changes

Frequently Asked Questions

What is the exact file path for the openai.yaml configuration?

The file must reside at plugins/<your-plugin>/skills/<skill-name>/agents/openai.yaml within the repository. For example, the Zotero plugin uses plugins/zotero/skills/zotero/agents/openai.yaml to define its agent interface.

Do I need to manually register the agent in the plugin manifest?

No. The platform automatically discovers agents by scanning the agents/ directory for openai.yaml files. The .codex-plugin/plugin.json manifest updates automatically to include these definitions, eliminating manual registration steps.

What image formats are supported for agent icons?

The icon_small and icon_large fields accept relative paths to standard web image formats, typically PNG or SVG files. Place these assets in the same directory or a subdirectory (such as assets/) relative to the openai.yaml file.

How do I restrict an agent to explicit invocation only?

Set allow_implicit_invocation: false in the policy section of your openai.yaml. This configuration forces the model to invoke the agent through explicit tool calls rather than automatic selection based on user intent matching.

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