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

> Learn how to structure plugin-level agents and skills in OpenAI plugins. Understand roles of orchestrators versus executable capabilities for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: architecture
- Published: 2026-06-27

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/openai.yaml) file that specifies its role and invocation policies.

For example, the Zoom plugin defines reviewer agents in [`plugins/zoom/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/openai.yaml) file defines the agent's short description, default prompt, and security policies.

```yaml

# 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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)

### Skill Manifests (SKILL.md)

Skills use [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) to declare input schemas, output contracts, and execution commands.

```markdown

# 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json):

```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:

```yaml

# 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:

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

```

## Discovery and Registration

Every plugin must contain a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), which points to the `plugins/` directory for scanning.

## Summary

- **Agents** live in `agents/` directories and use [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) for configuration and policy definitions
- **Skills** live in `skills/<skill>/` directories and use [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and discovery via [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file to define how the Codex engine executes the capability.