# How to Add Custom Agents to a Codex Plugin Using agents/openai.yaml

> Learn to add custom agents to a Codex plugin using agents/openai.yaml. Configure metadata and prompts for automatic runtime discovery. Enhance your plugin's capabilities today.

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

---

**You can add custom agents to a Codex plugin by creating an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file inside a skill directory, populating the `interface` section with metadata and prompt instructions, and relying on the runtime's automatic discovery mechanism without writing additional registration code.**

The openai/plugins repository enables developers to extend Codex with custom skills that use specialized LLM agents. To define how a large language model behaves when invoking your skill, you configure the agent's identity and system instructions in a structured YAML file located within the skill's directory.

## Understanding the agents/openai.yaml Structure

The [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file serves as the contract between your skill implementation and the LLM runtime. When the plugin loader scans the repository, it parses these YAML files to build the system prompts and UI metadata for each available agent.

### The interface Section

Every [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) must contain a top-level `interface` mapping. This object describes the agent's presentation layer and behavioral instructions. According to the repository's loader implementation (located in `src/loader/*.ts`), the runtime extracts this section using standard YAML parsing libraries like `js-yaml` and stores the configuration for prompt construction.

### Required Configuration Fields

The `interface` object requires the following fields to properly register an agent:

- **`display_name`**: The human-readable name shown in the Codex UI.
- **`short_description`**: A concise explanation of the agent's capabilities displayed alongside the name.
- **`icon_small`**: Relative path to a small icon asset (SVG or PNG) within the skill folder.
- **`icon_large`**: Relative path to a large icon asset for detailed views.
- **`default_prompt`**: The system prompt text that guides the LLM's behavior when the skill is invoked.

## Step-by-Step Guide to Adding a Custom Agent

Follow these steps to create a new agent that the Codex runtime will automatically discover and load.

1. **Create the skill directory structure** under `plugins/<your-plugin>/skills/<skill-name>/`. This directory will contain your implementation code and agent configuration.

2. **Add the agents/openai.yaml file** inside the skill folder at `plugins/<your-plugin>/skills/<skill-name>/agents/openai.yaml`. The file must reside in the `agents` subdirectory to be recognized by the loader.

3. **Populate the interface fields** with appropriate metadata. The `default_prompt` field is particularly critical, as it defines the initial instructions the model receives when your skill is called.

4. **Add icon assets** (optional but recommended) in the skill folder and reference them using relative paths in the `icon_small` and `icon_large` fields.

5. **Commit the files** to the repository. The runtime automatically walks the `plugins/**/skills/**` tree at startup, requiring no manual registration in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) unless you need to expose additional metadata beyond the agent definition.

## Real-World Examples from the Repository

The openai/plugins repository contains several production implementations of agent configurations. Examining these files provides concrete guidance on structuring your own agents.

### GitHub Skill Agent

The file [`plugins/github/skills/github/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/github/skills/github/agents/openai.yaml) demonstrates a complete agent definition for GitHub operations. This configuration defines how the LLM should behave when processing GitHub-related requests, including the display metadata and system instructions that shape the agent's responses.

### Plugin Creator Agent

Located at [`.agents/skills/plugin-creator/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/agents/openai.yaml), this internal tooling example shows how the repository maintains its own plugin development agents. This file illustrates advanced prompt engineering patterns used to guide the LLM through plugin creation tasks.

## Runtime Loading and Automatic Discovery

The plugin runtime implements a filesystem-based discovery mechanism that eliminates the need for manual agent registration. When the loader initializes, it recursively scans the `plugins/` directory for skills containing [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) files.

According to the source code analysis, the loader:
- Parses each discovered YAML file to extract the `interface` object.
- Registers the agent using the `display_name` as the identifier.
- Associates the `default_prompt` with the skill's invocation context.
- Loads referenced icon assets for UI rendering.

Because this process occurs automatically at startup, **no code changes are required** in the plugin manifest ([`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)) when adding new agents. The mere presence of a correctly structured [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file within a skill directory is sufficient for registration.

## Complete Working Example

Below is a minimal implementation of a Markdown Assistant skill with a custom agent configuration.

### Directory Structure

```bash
my-plugin/
├── .codex-plugin/
│   └── plugin.json          # plugin manifest (auto-discovered)

└── skills/
    └── markdown-assistant/
        ├── main.py           # your implementation

        ├── agents/
        │   └── openai.yaml   # custom agent definition

        └── assets/
            ├── markdown.svg
            └── markdown-small.svg

```

### agents/openai.yaml Content

```yaml
interface:
  display_name: "Markdown Assistant"
  short_description: "Generate, format, and lint Markdown documents"
  icon_small: "./assets/markdown-small.svg"
  icon_large: "./assets/markdown.svg"
  default_prompt: |
    You are a Markdown expert. When called, you will:
    • Generate well‑structured Markdown from user instructions.
    • Fix formatting errors and suggest improvements.
    • Keep output strictly in Markdown (no extra explanations).

```

When a user invokes this skill with a request like "write a README for a Python package," the runtime constructs the following prompt exchange:

```text
System: You are a Markdown expert. When called, you will:
• Generate well‑structured Markdown from user instructions.
• Fix formatting errors and suggest improvements.
• Keep output strictly in Markdown (no extra explanations).
User: Write a README for a Python package called "fast-api-utils".

```

## Summary

- **Create** an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file inside your skill's directory at `plugins/<plugin>/skills/<skill>/agents/`.
- **Define** the `interface` section with `display_name`, `short_description`, `icon_small`, `icon_large`, and `default_prompt`.
- **Reference** real-world examples in [`plugins/github/skills/github/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/github/skills/github/agents/openai.yaml) and [`.agents/skills/plugin-creator/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/agents/openai.yaml) for guidance.
- **Rely** on automatic discovery—the runtime scans `plugins/**/skills/**` and registers agents without manual manifest updates.
- **Customize** the `default_prompt` to shape LLM behavior and provide specific instructions for your use case.

## Frequently Asked Questions

### Do I need to update plugin.json when adding a new agent?

No. The Codex runtime automatically discovers agents by scanning the `plugins/**/skills/**` directory tree for [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) files. You only need to modify [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) if you are exposing additional metadata or entry points beyond the standard agent configuration.

### What image formats are supported for agent icons?

The repository examples use SVG and PNG formats for the `icon_small` and `icon_large` fields. These paths should be specified relative to the skill's root directory. Ensure the referenced files exist in your skill's asset folder before committing.

### Can I define multiple agents within a single skill?

While the standard structure associates one [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file per skill, you can create multiple skills within a single plugin, each with its own agent configuration. Place each skill in a separate directory under `plugins/<your-plugin>/skills/` with its own [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file.

### How does the default_prompt field influence the LLM?

The `default_prompt` field contains the system instructions that precede user queries when your skill is invoked. This text shapes the agent's personality, defines output formats, and establishes behavioral constraints. According to the loader implementation, this prompt is injected at the beginning of every interaction with the skill.