How to Create Skill-Specific Agent Configurations in OpenAI Plugins

To create a skill-specific agent configuration, add an 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/<plugin-name>/skills/<skill-name>/. For example, the Google Sheets skill lives at plugins/google-drive/skills/google-sheets/. The platform discovers skills by reading the 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 configuration file. The platform specifically looks for this path as a sibling to the SKILL.md file during the skill loading process.

Define the Agent Interface

Create 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 $<skill-name> 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 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 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 $<skill-name> 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, the skill can be triggered automatically when the model determines relevance.

Complete Configuration Example

Here is a production-ready openai.yaml file for a hypothetical skill:

# 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 to identify the skill name, the runtime checks for a sibling 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 already lists the skills/ directory, so no additional registration is required for new agent configurations to load.

Summary

• Agent configurations live in plugins/<plugin>/skills/<skill>/agents/openai.yaml alongside the skill's SKILL.md file.
• The interface section controls UI display names, icons, colors, and the default_prompt that feeds the $<skill-name> 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. 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 $<skill-name>, where <skill-name> 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.

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 $<skill-name> prompt interpolation that the agent configuration provides. The skill may also default to allow_implicit_invocation: false.

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