Creating Agent Configurations Within OpenAI Plugins: A Complete Developer Guide

Creating agent configurations within OpenAI plugins requires defining YAML agent files in plugins/<name>/agents/ or nested within skills/ directories, registering them in the plugin.json manifest, and setting interface prompts and policies that govern LLM behavior.

The openai/plugins repository provides a modular framework for extending OpenAI’s Codex platform through self-contained plugin packages. Creating agent configurations within OpenAI plugins allows developers to declaratively specify how large language models invoke specific skills, manage system prompts, and enforce execution policies. Each plugin operates as an isolated unit under the plugins/ directory, enabling the Codex runtime to automatically discover capabilities and expose them as callable agents.

Understanding the Plugin Architecture

The openai/plugins repository follows a predictable layout that enables the Codex runtime to discover plugin capabilities and run agents. Each plugin package contains several key components that work together to expose skills to the LLM.

The Plugin Manifest at plugins/<name>/.codex-plugin/plugin.json declares the plugin’s metadata, including its name, version, description, and capabilities. It also points the runtime to the plugin’s skills, apps, and MCP servers.

Skills reside in plugins/<name>/skills/ and serve as reusable building blocks that implement specific functionality. Each skill may contain a SKILL.md description, optional nested agents/ directories, and reference data.

Agents are defined in YAML files located at plugins/<name>/agents/*.yaml or within skill-specific directories at plugins/<name>/skills/**/agents/*.yaml. These files describe how an LLM should invoke a skill, including default prompts, policies, and UI metadata.

Commands are human-oriented markdown files stored in plugins/<name>/commands/*.md that document CLI-style shortcuts for common tasks. The Codex-Run system parses these to expose command-line entry points.

Optional configuration files include .app.json and .mcp.json in the plugin root, which define additional runtime services and UI assets. The Marketplace Index at .agents/plugins/marketplace.json maps plugin names to their directories, enabling the runtime to locate all available plugins in the repository.

Step-by-Step Agent Configuration Flow

Creating a functional agent configuration involves five distinct steps that connect your skill logic to the Codex runtime.

Define the Plugin Manifest

Begin by creating the plugin.json file at plugins/<name>/.codex-plugin/plugin.json. This JSON file must include the plugin’s metadata and point to the skills/ folder. The runtime uses this manifest to register the plugin and discover its capabilities.

Write a Skill

Add a directory under plugins/<name>/skills/ that implements the core logic for your capability. This typically contains scripts, API calls, or business logic that the agent will orchestrate. Each skill should be self-contained and may include documentation in a SKILL.md file.

Configure Agent YAML Files

Create an agent definition file at plugins/<name>/agents/openai.yaml or within a specific skill at plugins/<name>/skills/<skill-name>/agents/openai.yaml. The YAML file specifies the LLM prompt, invocation policy, and UI metadata.

# plugins/example/skills/do-thing/agents/openai.yaml

interface:
  display_name: Do Thing
  short_description: Executes the “do‑thing” skill.
  default_prompt: |
    Perform the requested operation using the “do‑thing” skill.
policy:
  allow_implicit_invocation: false

The interface block defines how the agent appears to users, while the policy block controls runtime behavior such as implicit invocation.

Document Commands

Create optional markdown files in plugins/<name>/commands/ to provide end-users with friendly CLI shortcuts. These files are parsed by the Codex-Run system to expose command-line entry points like implement-from-figma.

Update the Marketplace

The repository’s .agents/plugins/marketplace.json is automatically refreshed by CI scripts; no manual edit is required. This index enables the Codex runtime to locate and load your plugin.

Practical Code Examples

The following examples demonstrate the complete configuration for a new agent.

Minimal Agent Definition

This YAML file creates a basic agent configuration for a hypothetical "do-thing" skill:

# plugins/example/skills/do-thing/agents/openai.yaml

interface:
  display_name: Do Thing
  short_description: Executes the “do‑thing” skill.
  default_prompt: |
    Perform the requested operation using the “do‑thing” skill.
policy:
  allow_implicit_invocation: false

Plugin Manifest Reference

Add the skill to your plugin manifest by updating plugins/example/.codex-plugin/plugin.json:

{
  "name": "example",
  "version": "0.1.0",
  "description": "Demo plugin showing how to add a new agent",
  "skills": "./skills/",
  "interface": {
    "displayName": "Example",
    "shortDescription": "Demo plugin"
  }
}

Running the Agent via CLI

Once configured, invoke the agent through the Codex-Run system:

codex-run example do-thing "Create a sample report for Q2"

Key Files and References

The openai/plugins repository contains several reference implementations that demonstrate production-ready agent configurations.

The Figma plugin manifest at plugins/figma/.codex-plugin/plugin.json demonstrates the required fields for linking skills and defining plugin metadata.

The Figma agent definition at plugins/figma/agents/openai.yaml shows the YAML structure used by the runtime to expose an agent, including interface specifications and policy settings.

The Implement-from-Figma command at plugins/figma/commands/implement-from-figma.md provides a user-facing command that invokes the agent through the CLI.

The Marketplace Index at .agents/plugins/marketplace.json serves as the central registry that enables the Codex runtime to locate all plugins in the repository.

Summary

• Agent configurations in OpenAI plugins are defined through YAML files located in plugins/<name>/agents/ or nested within skills/ directories.
• The plugin.json manifest at plugins/<name>/.codex-plugin/plugin.json registers the plugin and points to its skills.
• Each agent YAML specifies prompts, policies (such as allow_implicit_invocation), and UI metadata that control LLM behavior.
• Commands in plugins/<name>/commands/*.md provide CLI shortcuts for invoking agents.
• The marketplace index at .agents/plugins/marketplace.json is automatically maintained to enable runtime discovery.

Frequently Asked Questions

Where do agent configuration files reside in an OpenAI plugin?

Agent configuration files reside in plugins/<name>/agents/*.yaml or within skill-specific directories at plugins/<name>/skills/**/agents/*.yaml. The Codex runtime recursively scans these locations to discover agent definitions and load them into the system.

What is the purpose of the plugin.json manifest file?

The plugin.json file located at plugins/<name>/.codex-plugin/plugin.json declares the plugin’s metadata, version, and capabilities. It serves as the entry point that tells the Codex runtime where to find skills, apps, and MCP servers, effectively registering the plugin for discovery.

How do I prevent implicit invocation of an agent?

Set allow_implicit_invocation: false within the policy block of your agent YAML file. This policy setting ensures the Codex runtime only invokes the agent when explicitly requested, preventing automatic execution during unrelated conversations.

What is the role of the marketplace.json file?

The .agents/plugins/marketplace.json file acts as a central registry that maps plugin names to their directory locations. Maintained automatically by CI scripts, it enables the Codex runtime to discover and load all available plugins within the repository without manual configuration.

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