Where Are Optional Companion Surfaces Located Within a Plugin Directory?

Optional companion surfaces in an OpenAI plugin are located in well-defined subdirectories and files within the plugin folder, including skills/, agents/, commands/, assets/, and configuration files like hooks.json, .app.json, and .mcp.json relative to the plugin root.

Every OpenAI plugin requires a mandatory manifest at .codex-plugin/plugin.json that defines its core identity. Beyond this required file, you can add optional companion surfaces to extend functionality, expose additional entry points, or provide auxiliary assets. According to the openai/plugins repository, these surfaces are automatically discovered by the Codex runtime when placed in their conventional locations.

Standard Directory Layout

The plugin directory structure follows a predictable pattern. While the manifest at .codex-plugin/plugin.json is mandatory, all other surfaces are optional and reside in specific paths relative to plugins/<name>/.

Required Foundation

The mandatory manifest serves as the entry point:

• .codex-plugin/plugin.json — Core manifest declaring plugin name, version, and capabilities

Skill Implementations

Place skill definitions in the skills/ directory. This folder contains subdirectories for each skill, including SKILL.md files and supporting scripts.

skills/hello_world/
├── SKILL.md
└── scripts/
    └── hello.py

Plugin-Level Agents

Agent configurations that enable autonomous planning or execution belong in agents/. These are typically YAML files.

agents/
└── planner.yaml

Command Definitions

Custom commands invocable from the chat interface live in commands/ as Markdown files.

commands/
└── greet.md

Lifecycle Hooks

The hooks.json file declares lifecycle hooks such as onCreate and onUpdate for the plugin.

Static Assets

Store images, icons, and other UI resources in assets/.

assets/
└── icon.png

Configuration Metadata

Two optional JSON files provide additional configuration:

• .app.json — Configuration for standalone app mode (UI defaults)
• .mcp.json — Metadata for Multi-Component Plugins (MCP) that bundle multiple sub-plugins

Complete Directory Example

Below is a minimal example of a plugin named example that includes several optional companion surfaces:

plugins/example/
├─ .codex-plugin/
│  └─ plugin.json            # Required manifest

├─ skills/
│  ├─ hello_world/
│  │  ├─ SKILL.md           # Skill definition

│  │  └─ scripts/
│  │     └─ hello.py
│  └─ math/
│     └─ SKILL.md
├─ agents/
│  └─ planner.yaml           # Optional agent configuration

├─ commands/
│  └─ greet.md               # Optional custom command

├─ hooks.json                # Optional lifecycle hooks

├─ assets/
│  └─ icon.png               # Optional static asset

├─ .app.json                 # Optional app-level configuration

└─ .mcp.json                 # Optional multi-component metadata

In this layout, the skills/ folder contains two skills (hello_world and math), while agents/ defines a planner agent that orchestrates skill calls. The commands/ folder provides a greet command triggerable by the model, and hooks.json registers lifecycle callbacks.

Runtime Discovery Process

When a plugin directory contains any of these optional items, the corresponding surface is automatically discovered by the Codex runtime and made available to the model without additional registration. This convention-over-configuration approach is documented in the repository's top-level README.md (lines 5-8), which specifies the standard paths for all optional companion surfaces.

Summary

• Mandatory manifest: Every plugin requires .codex-plugin/plugin.json as the core identity file.
• Skills directory: Place skill implementations in skills/ with SKILL.md files and supporting scripts.
• Agents directory: Store agent configurations in agents/ using YAML files.
• Commands directory: Define chat commands in commands/ as Markdown files.
• Hooks file: Declare lifecycle events in hooks.json at the plugin root.
• Assets directory: Include static resources like icons in assets/.
• Config files: Use .app.json for app-level settings and .mcp.json for multi-component plugin metadata.

Frequently Asked Questions

What is the difference between skills and agents in the optional companion surfaces?

Skills reside in skills/ and represent fine-grained actions exposed to the model through SKILL.md files and scripts. Agents reside in agents/ and contain YAML configurations that enable autonomous planning or execution workflows, orchestrating how skills are called rather than defining the actions themselves.

Is the hooks.json file required for all plugins?

No, hooks.json is entirely optional. You only need to include it if your plugin requires lifecycle callbacks such as onCreate or onUpdate to execute setup or cleanup logic when the plugin loads or updates.

Can I create a valid plugin without any optional companion surfaces?

Yes. A plugin only requires the mandatory manifest at .codex-plugin/plugin.json to function. All companion surfaces—including skills/, agents/, commands/, and configuration files—are optional extensions that add functionality but are not required for basic plugin operation.

How does the Codex runtime locate static assets referenced by the plugin?

The runtime looks for static assets in the assets/ directory at the plugin root. Files like images and icons placed here are automatically available to the plugin UI without explicit path configuration in the manifest.

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