# Creating Agent Configurations Within OpenAI Plugins: A Complete Developer Guide > Learn to create agent configurations in OpenAI plugins by defining YAML files and registering them in plugin.json. Control LLM behavior with interface prompts and policies. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-07-02 --- **Creating agent configurations within OpenAI plugins requires defining YAML agent files in `plugins//agents/` or nested within `skills/` directories, registering them in the [`plugin.json`](https://github.com/openai/plugins/blob/main/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//.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//skills/` and serve as reusable building blocks that implement specific functionality. Each skill may contain a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) description, optional nested `agents/` directories, and reference data. **Agents** are defined in YAML files located at `plugins//agents/*.yaml` or within skill-specific directories at `plugins//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//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`](https://github.com/openai/plugins/blob/main/.app.json) and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) in the plugin root, which define additional runtime services and UI assets. The **Marketplace Index** at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) file at `plugins//.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//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`](https://github.com/openai/plugins/blob/main/SKILL.md) file. ### Configure Agent YAML Files Create an agent definition file at `plugins//agents/openai.yaml` or within a specific skill at `plugins//skills//agents/openai.yaml`. The YAML file specifies the LLM prompt, invocation policy, and UI metadata. ```yaml # 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//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`](https://github.com/openai/plugins/blob/main/.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: ```yaml # 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`](https://github.com/openai/plugins/blob/main/plugins/example/.codex-plugin/plugin.json): ```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: ```bash 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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//agents/` or nested within `skills/` directories. - The **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest** at `plugins//.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//commands/*.md` provide CLI shortcuts for invoking agents. - The **marketplace index** at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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//agents/*.yaml` or within skill-specific directories at `plugins//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`](https://github.com/openai/plugins/blob/main/plugin.json) file located at `plugins//.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`](https://github.com/openai/plugins/blob/main/.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.