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

You add agents to a plugin by placing an openai.yaml file inside a skill's agents/ directory, which exposes UI metadata and optional invocation policies to the OpenAI platform without requiring manual entries in the plugin manifest.

The openai/plugins repository defines a convention where each skill registers agent entry-points through a single YAML configuration file. This approach lets the OpenAI plugin marketplace discover, display, and enforce runtime policies for each agent automatically.

How Agent Discovery Works

The platform scans every skill's agents/ folder for a file named openai.yaml. When the file is present, the plugin manifest at .codex-plugin/plugin.json automatically picks up the agent, as demonstrated in the repository's generic structure under plugins/github/.codex-plugin/plugin.json. This means you do not need to add manual references to plugin.json because the CI validation and runtime discovery process handles registration directly.

The convention applies across all skills. For instance, the Google Sheets skill stores its agent metadata under plugins/google-drive/skills/google-sheets/agents, while the Zotero skill defines its canonical example at plugins/zotero/skills/zotero/agents/openai.yaml.

• The target path is plugins/<your-plugin>/skills/<skill-name>/agents/openai.yaml.
• After validation, the agent appears under the plugin's Agents tab in the OpenAI Plugin Store.

Configuring the openai.yaml Interface Section

Every openai.yaml file must contain an interface block that supplies human-readable metadata for the marketplace and the ChatGPT UI. The standard fields include:

• display_name — The human-readable name shown in the marketplace and ChatGPT.
• short_description — A brief tagline summarizing the agent's purpose.
• icon_small — Relative path to a small icon asset (PNG or SVG).
• icon_large — Relative path to a large icon asset.
• default_prompt — The system prompt or persona text used when the agent is invoked.

The following example mirrors the canonical format from 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."

Place the referenced icon assets in the same directory or a dedicated sub-folder so that relative paths resolve correctly during packaging.

Adding a Policy Block to openai.yaml

The optional policy section supplies fine-grained invocation controls for the OpenAI runtime. When defined, these fields govern whether the model can select the agent automatically or must be called explicitly, as well as token budgets and concurrency limits.

Key policy fields include:

• allow_implicit_invocation — When true, the model may automatically route requests to this agent based on capability matching. When false, the agent requires an explicit tool call.
• explicit_only_invoke_cost_tokens — Sets an upper bound on token cost for explicit-only invocations, which is useful for expensive operations like code generation.
• estimated_static_policy_aware — When true, the runtime treats the agent as static for budgeting purposes, preventing inflation of the implicit-invocation score.
• max_concurrency — (Advanced) Limits the number of parallel executions allowed for this agent.

All policy keys are documented in the OpenAI specification; refer to the generic "Agent policy" reference in the repository's README.md at the root of openai/plugins.

Step-by-Step: Add Agents to a Plugin Using openai.yaml

Follow these steps to register a new agent in your plugin.

1. Create the agents/ folder inside the target skill directory at plugins/<your-plugin>/skills/<skill-name>/agents/.

2. Add the openai.yaml file to that folder with the required interface metadata and optional policy block.

3. Provide the icon assets referenced by icon_small and icon_large in the skill directory or a sub-folder such as ./assets/.

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

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

Complete openai.yaml Examples

Minimal Agent Configuration (Zotero-Style)

Use this pattern when you only need to expose metadata and a default prompt:

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

Agent with Policy Restrictions

Use this pattern when you need strict invocation controls and cost caps:

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

Expected Directory Layout

The following tree shows where openai.yaml lives relative to the skill and manifest:

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

The openai.yaml file sits at plugins/my-plugin/skills/sql-gen/agents/openai.yaml, while .codex-plugin/plugin.json discovers and includes the agent automatically.

Summary

• Place an openai.yaml file inside the skill's agents/ directory to register a new agent with the OpenAI platform.
• The interface section provides required UI metadata such as display_name, short_description, icon paths, and default_prompt.
• The optional policy section controls runtime behavior with fields like allow_implicit_invocation and explicit_only_invoke_cost_tokens.
• The .codex-plugin/plugin.json manifest discovers agents automatically; no manual manifest edits are required.
• Committing the file triggers CI validation, after which the agent appears in the OpenAI Plugin Store.

Frequently Asked Questions

Where must the openai.yaml file be located?

The file must be placed at plugins/<your-plugin>/skills/<skill-name>/agents/openai.yaml inside the repository. The platform scans every agents/ directory for this filename and registers any valid configuration it finds.

Do I need to edit plugin.json to register a new agent?

No. The .codex-plugin/plugin.json manifest automatically discovers agents by scanning the agents/ folders across skills. According to the openai/plugins source structure, no extra entries are required in the manifest file.

What is the purpose of the policy block in openai.yaml?

The policy block governs how the OpenAI runtime invokes the agent. For example, setting allow_implicit_invocation: false forces explicit tool calls only, while explicit_only_invoke_cost_tokens places a hard cap on token spend for that agent's executions.

How do icon paths work in openai.yaml?

The icon_small and icon_large fields accept relative paths from the agents/ directory to image assets, typically PNG or SVG files. Store these assets in the same folder or a sub-directory such as ./assets/ so the packaging process resolves them correctly.

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