How to Structure Plugin-Level Agents Versus Plugin-Level Skills in OpenAI Plugins

Plugin-level agents reside in agents/ directories and act as orchestrators or reviewers, while plugin-level skills live in skills/ directories and provide executable capabilities accessed via SKILL.md manifests.

The openai/plugins repository establishes strict conventions for organizing autonomous components. Understanding how to structure plugin-level agents versus plugin-level skills ensures your extension integrates cleanly with the Codex runtime and marketplace discovery system.

Directory Structure Conventions

The repository enforces a clear separation between orchestration logic and functional capabilities through specific directory layouts.

Plugin-Level Agents Location

Agents are defined at the plugin root under agents/. Each agent configuration resides in an openai.yaml file that specifies its role and invocation policies.

For example, the Zoom plugin defines reviewer agents in plugins/zoom/agents/openai.yaml.

Plugin-Level Skills Location

Skills reside in individual subdirectories under skills/. Each skill is a self-contained unit with its own manifest, implementation scripts, and reference documentation.

The Figma plugin demonstrates this structure with plugins/figma/skills/figma-use-slides/SKILL.md.

Configuration and Manifest Files

Both components require specific manifest formats to register with the runtime and declare their interfaces.

Agent Configuration (openai.yaml)

The openai.yaml file defines the agent's short description, default prompt, and security policies.

# plugins/example/agents/openai.yaml

short_description: "Example reviewer agent for policy checks"
default_prompt: |
  Use this agent to audit the plugin's security posture.
policy:
  allow_implicit_invocation: false   # keep the agent explicit

Key implementation details:

• Agents include a policy block with allow_implicit_invocation: false to prevent implicit selection by the runtime
• Configurations are referenced in .agents/plugins/marketplace.json

Skill Manifests (SKILL.md)

Skills use SKILL.md to declare input schemas, output contracts, and execution commands.

# plugins/example/skills/sample-skill/SKILL.md

title: Sample Skill
description: |
  Demonstrates a simple skill that echoes the input text.
inputs:
  - name: text
    type: string
    description: Text to be echoed.
outputs:
  - name: echoed_text
    type: string
    description: The same text that was supplied.

run:
  command: python scripts/main.py "{{text}}"

Functional Differences and Use Cases

Agents function as reviewer or orchestrating components. They can launch sub-skills in parallel, utilize tool loops, and return structured JSON contracts. Agents typically enforce policies or coordinate complex multi-step workflows.

Skills provide direct executable capabilities. The Codex engine invokes them directly based on the SKILL.md specification, executing scripts located in the scripts/ directory.

Implementation Examples

Registering Components in the Marketplace

Both agents and skills are enumerated in .agents/plugins/marketplace.json:

{
  "plugins": [
    {
      "name": "example",
      "path": "plugins/example",
      "agents": ["agents/openai.yaml"],
      "skills": ["skills/sample-skill"]
    }
  ]
}

Orchestrating Multiple Skills via Agents

Agents can coordinate parallel skill execution through their default prompts:

# agents/openai.yaml (excerpt)

default_prompt: |
  You are a coordination agent. Run the following skills concurrently:
  - skill: figma-use-slides
    input: { slide_id: "123" }
  - skill: figma-use-motion
    input: { animation: "fade_in" }

The orchestrator dispatches both skills, collects their JSON returns, and merges the results into a unified response block.

Returning Structured Data

Skills return JSON contracts following the RETURN_CONTRACT pattern:

{
  "status": "success",
  "data": {
    "slide_id": "123",
    "animation": "fade_in"
  }
}

Discovery and Registration

Every plugin must contain a .codex-plugin/plugin.json root manifest that enumerates available skills and agents. The runtime discovers these components through the marketplace file at .agents/plugins/marketplace.json, which points to the plugins/ directory for scanning.

Summary

• Agents live in agents/ directories and use openai.yaml for configuration and policy definitions
• Skills live in skills/<skill>/ directories and use SKILL.md manifests to declare execution flows
• Agents serve as orchestrators with explicit invocation policies; skills provide direct callable functionality
• Both require registration in .codex-plugin/plugin.json and discovery via .agents/plugins/marketplace.json
• Agents can launch skills in parallel and return structured JSON contracts consumed by the orchestrator

Frequently Asked Questions

Can a single plugin contain both agents and skills?

Yes. A plugin can define multiple agents under agents/ and multiple skills under skills/. The .codex-plugin/plugin.json manifest enumerates both component types, allowing the runtime to discover and invoke them according to their respective contracts.

What prevents an agent from being implicitly invoked by the runtime?

Setting allow_implicit_invocation: false in the agent's openai.yaml policy block restricts the agent to explicit invocation only. This prevents the runtime from automatically selecting the agent for general tasks that match its description.

How do agents handle results from multiple skills running in parallel?

Agents utilize the RETURN_CONTRACT pattern to collect structured JSON responses from each skill. The orchestrator parses these results and merges them into a single response block returned to the caller.

Where should skill implementation code be stored?

Place skill implementation scripts in plugins/<plugin>/skills/<skill>/scripts/. Reference these scripts in the run.command field of the skill's SKILL.md file to define how the Codex engine executes the capability.

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