# How to Create Skill-Specific Agent Configurations in OpenAI Plugins > Learn to create skill-specific agent configurations in OpenAI plugins by adding an openai yaml file to your skill folder. Define interface and policy for custom agents. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-23 --- **To create a skill-specific agent configuration, add an [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file inside the `agents/` subdirectory of your skill folder, defining the `interface` fields (display name, description, icons, default prompt) and optional `policy` settings.** The openai/plugins repository powers the Instagit (Codex Plugins) platform, which discovers agent configurations by scanning for YAML files alongside skill definitions. When you create skill-specific agent configurations, you control how the skill appears in the UI, define the system instructions the model receives, and set invocation policies that determine automatic triggering behavior. ## Step-by-Step Guide to Creating Agent Configurations ### Locate the Skill Folder All skills reside under the path `plugins//skills//`. For example, the Google Sheets skill lives at `plugins/google-drive/skills/google-sheets/`. The platform discovers skills by reading the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file in this directory, which declares the skill's name and metadata. ### Create the Agents Directory Inside your skill folder, create an `agents/` subdirectory if it does not already exist. This directory will contain the [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) configuration file. The platform specifically looks for this path as a sibling to the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file during the skill loading process. ### Define the Agent Interface Create [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) with an `interface:` section containing the following fields: - **display_name**: The human-readable name shown in the Instagit UI - **short_description**: A brief explanation of the skill's purpose - **icon_small** and **icon_large**: Relative paths to SVG assets (e.g., `./assets/icon-small.svg`) - **brand_color**: Hex color code for UI theming - **default_prompt**: The system instructions injected when the skill is invoked The `default_prompt` field populates the `$` variable in prompts. For a skill named `google-sheets`, the text you provide replaces the placeholder `$google-sheets` in the model's context window. ### Configure Invocation Policy Add an optional `policy:` section to control automatic invocation. Set `allow_implicit_invocation: true` to let the model call the skill without an explicit user request. This flag defaults to `false` when omitted. ## Agent Configuration Schema Reference The [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file follows a strict schema parsed by the Instagit runtime. According to the source code analysis, the platform expects these specific structures: **Interface Fields** The `interface` object in [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) must define the visual and behavioral metadata. The `display_name` and `short_description` render in the skill selection UI, while `brand_color` applies theming. Icon paths resolve relative to the skill folder, allowing custom assets stored in `./assets/`. **Prompt Injection Mechanism** The `default_prompt` content becomes the value of the `$` variable. When the runtime processes the skill, it interpolates this text into the system prompt, giving the model specific instructions for that skill's capabilities. **Policy Flags** Currently, the only supported policy is `allow_implicit_invocation`. When set to `true` in [`plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml), the skill can be triggered automatically when the model determines relevance. ## Complete Configuration Example Here is a production-ready [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file for a hypothetical skill: ```yaml # plugins/example-plugin/skills/example-skill/agents/openai.yaml interface: display_name: "Example Skill" short_description: "Summarize text and extract key ideas" icon_small: "./assets/example-small.svg" icon_large: "./assets/example.svg" brand_color: "#123456" default_prompt: | Use $example-skill to read the provided document, create a concise summary, and list the three most important take-aways. policy: allow_implicit_invocation: true ``` This configuration: - Displays "Example Skill" in the Instagit interface with custom icons - Injects the multi-line prompt whenever `$example-skill` appears in the system context - Allows the model to invoke the skill automatically without explicit user commands ## How the Runtime Loads Agent Configurations When Instagit initializes, it performs skill discovery by scanning `plugins/**/skills/**/SKILL.md` files. After parsing the front-matter in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) to identify the skill name, the runtime checks for a sibling [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file. If present, the platform: 1. Reads the `interface` data to build UI bubbles and populate metadata 2. Stores the `default_prompt` for variable interpolation 3. Applies `policy` settings to the invocation router The plugin manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) already lists the `skills/` directory, so no additional registration is required for new agent configurations to load. ## Summary - **Agent configurations** live in `plugins//skills//agents/openai.yaml` alongside the skill's [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file. - The **interface** section controls UI display names, icons, colors, and the `default_prompt` that feeds the `$` variable. - Set **allow_implicit_invocation** to `true` in the policy section to enable automatic skill triggering. - The Instagit **runtime automatically discovers** new configurations on the next plugin load without manifest updates. ## Frequently Asked Questions ### What file format does the agent configuration use? The agent configuration uses **YAML format** specifically named [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml). This file must reside inside an `agents/` subdirectory within the skill folder. The Instagit runtime parses this file to extract interface metadata and policy settings. ### How do I reference the skill in my prompts? Reference the skill using the **dollar-sign variable syntax** `$`, where `` matches the skill's directory name. For example, a skill in `plugins/google-drive/skills/google-sheets/` uses the variable `$google-sheets`. The runtime replaces this placeholder with the text defined in the `default_prompt` field of [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml). ### Can I use custom icons for my skill's agent? Yes. Specify **relative paths** in the `icon_small` and `icon_large` fields of the `interface` section, such as `./assets/icon.svg`. The platform resolves these paths relative to the skill folder root. Place your SVG assets in an `assets/` folder within the skill directory. ### What happens if I don't create an agents/openai.yaml file? If the file is missing, the skill **will not have a dedicated agent configuration**. While the underlying skill logic may still function, the Instagit UI will lack the custom display name, icons, colors, and the `$` prompt interpolation that the agent configuration provides. The skill may also default to `allow_implicit_invocation: false`.