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

> Easily add agents to your plugin with openai.yaml configuration. Expose UI metadata and invocation policies directly within your skill's agents directory. Learn how now.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-07

---

**You add agents to a plugin by placing an [`openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/openai.yaml). When the file is present, the plugin manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) automatically picks up the agent, as demonstrated in the repository's generic structure under [`plugins/github/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/github/.codex-plugin/plugin.json). This means you do not need to add manual references to [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

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

```

### Agent with Policy Restrictions

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

```yaml
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`](https://github.com/openai/plugins/blob/main/openai.yaml) lives relative to the skill and manifest:

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

```

The [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file sits at [`plugins/my-plugin/skills/sql-gen/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/skills/sql-gen/agents/openai.yaml), while [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) discovers and includes the agent automatically.

## Summary

- Place an [`openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.