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

You can add custom agents to a Codex plugin by creating an 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 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 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 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 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, 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 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) when adding new agents. The mere presence of a correctly structured 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

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

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:

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 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 and .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 files. You only need to modify .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 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 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.

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