# Where Are Optional Companion Surfaces Located Within a Plugin Directory?

> Discover where optional companion surfaces live in your OpenAI plugin directory. Find skills, agents, commands, assets, and config files like hooks.json easily.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/openai/plugins/blob/main/hooks.json), [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) relative to the plugin root.**

Every OpenAI plugin requires a mandatory manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/SKILL.md) files and supporting scripts.

```text
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.

```text
agents/
└── planner.yaml

```

### Command Definitions

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

```text
commands/
└── greet.md

```

### Lifecycle Hooks

The [`hooks.json`](https://github.com/openai/plugins/blob/main/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/`.

```text
assets/
└── icon.png

```

### Configuration Metadata

Two optional JSON files provide additional configuration:

- [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) — Configuration for standalone app mode (UI defaults)
- [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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:

```text
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) as the core identity file.
- **Skills directory**: Place skill implementations in `skills/` with [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/hooks.json) at the plugin root.
- **Assets directory**: Include static resources like icons in `assets/`.
- **Config files**: Use [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for app-level settings and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.