# What Are Commands Defined in a Plugin? Understanding the OpenAI Plugins Architecture

> Discover how commands defined in a plugin, stored in a commands/ directory, allow Codex agents to execute specific tasks within the OpenAI plugins architecture.

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

---

**Commands defined in a plugin are Markdown-based workflow specifications stored in a `commands/` directory that enable Codex agents to execute deterministic, self-contained tasks.**

The `openai/plugins` repository implements a documentation-first architecture where concrete actions are declared through structured Markdown rather than executable code. Each plugin—whether for Zoom, ClickUp, or Vercel—contains a **`commands/`** directory housing these definition files. These documents serve as the authoritative source for how Codex agents should approach specific tasks, from debugging broken integrations to managing resources.

## Anatomy of a Command Definition

A command is a self-contained Markdown document following strict conventions defined in [`plugins/zoom/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/_conventions.md). Every command file must include specific sections that guide the agent through a deterministic workflow.

### Front-matter and Description

Each command begins with YAML front-matter containing a human-readable description consumed by the UI. This metadata appears in the plugin marketplace and help interfaces.

```markdown
---
description: Triage a broken Zoom integration when the failing layer is not yet obvious.
---

```

According to the source code in [`plugins/zoom/commands/debug-zoom.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/debug-zoom.md), this front-matter allows the Codex runtime to index and display available commands without parsing the full document body.

### Preflight and Symptom Collection

The **Preflight** section mandates exact symptom capture before execution begins. This includes error text, failing endpoints, environment details, and whether the issue is deterministic or intermittent.

As implemented in [`plugins/zoom/commands/debug-zoom.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/debug-zoom.md), this section ensures agents gather sufficient context before attempting diagnosis, preventing premature fixes on incomplete information.

### The Plan Section

The **Plan** section enumerates hypotheses, identifies files to inspect, and declares whether the goal is diagnosis only or includes a fix. This establishes the agent's strategic approach before touching any code.

### Executable Steps and Verification

The **Commands** section lists discrete actions—typically following an "inventory," "narrow," "inspect," and "apply minimal correction" pattern. Each step references specific SDK methods, API endpoints, or configuration files.

The **Verification** section defines success criteria, requiring agents to re-run or reconstruct the failing path after applying fixes. This ensures commands produce measurable outcomes rather than speculative changes.

### Standardized Result Output

Every command concludes with a uniform **Result** block using a JSON-like structure:

```text

## Result

- Action: triaged a broken Zoom integration
- Status: success | partial | failed

```

This standardization allows the Codex runtime to parse outcomes programmatically, regardless of which specific plugin executed the command.

## Command Discovery and Execution Flow

The Codex runtime discovers commands through a predictable scanning process. Understanding this flow clarifies how the `commands/` directory integrates with the broader plugin architecture.

### Runtime Scanning Process

1. The agent scans the plugin directory for `commands/*.md` files
2. Each markdown file is parsed to extract front-matter and structured sections
3. The runtime builds a deterministic command registry mapping command names (filenames without `.md` extension) to their specifications

For example, the file [`plugins/zoom/commands/debug-zoom.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/debug-zoom.md) registers as the `/debug-zoom` command available to users.

### Agent Execution Model

When a user requests a specific command, the Codex agent:

- Loads the corresponding Markdown definition from the `commands/` directory
- Executes the Preflight and Plan sections, potentially requesting additional user input
- Performs the enumerated steps using actual API calls and SDK invocations
- Returns the structured Result block to the user interface

Critically, the command files themselves contain **no executable code**—they are pure documentation that the agent interprets to generate its execution plan.

## Plugin Metadata and Command Registration

Commands do not exist in isolation. They integrate with plugin metadata and skill definitions to form a complete capability declaration.

### Plugin Configuration

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file (visible in [`plugins/clickup/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/clickup/.codex-plugin/plugin.json)) declares the plugin name, version, and UI assets. This metadata links the marketplace presentation to the command implementations found in the `commands/` directory.

### Skill Documentation

Each plugin includes a **[`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)** file that provides high-level context about the plugin's capabilities and references the specific command set available in the `commands/` folder. This document bridges the gap between broad plugin functionality and concrete command implementations.

### Command Catalog

The [`README.md`](https://github.com/openai/plugins/blob/main/README.md) in each plugin directory serves as a human-readable catalog. As seen in [`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md), this file enumerates all deterministic commands available, providing users with an overview of what tasks the plugin can perform without browsing the `commands/` directory directly.

## Practical Example: Invoking a Plugin Command

While the command definitions reside in the repository, execution occurs through the Codex API. Below is a practical example of how a client application triggers a command defined in a plugin:

```python
import requests

# Example: ask Codex to run the Zoom debug command

payload = {
    "plugin": "zoom",
    "command": "debug-zoom",
    "input": "I get a 401 error when calling /v2/users/me"
}

resp = requests.post(
    "https://codex.openai.com/v1/execute",
    json=payload,
    headers={"Authorization": "Bearer <YOUR_API_KEY>"}
)

print(resp.json())

```

In this request, the `command` value corresponds directly to the filename [`debug-zoom.md`](https://github.com/openai/plugins/blob/main/debug-zoom.md) located in `plugins/zoom/commands/`. The Codex service loads this definition, executes the preflight checks, and returns the standardized result format defined in the command's Result section.

## Summary

- **Commands defined in a plugin** are Markdown documents stored in a top-level `commands/` directory, not executable scripts.
- Each command follows a strict template defined in [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md), including sections for Preflight, Plan, executable steps, Verification, and standardized Result output.
- The Codex runtime discovers commands by scanning `commands/*.md` files and registers them by filename (minus the `.md` extension).
- Command definitions are pure documentation; the actual API calls and SDK invocations are performed by the agent interpreting the command specification.
- Plugin metadata in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and skill definitions in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) work alongside the `commands/` directory to create a complete plugin capability profile.

## Frequently Asked Questions

### What file format are plugin commands written in?

Commands are written in **Markdown** (`.md` files). This documentation-first approach ensures that commands are human-readable while following a strict structural template that the Codex runtime can parse. The [`plugins/zoom/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/_conventions.md) file defines the required sections and formatting rules for all command documents.

### How does Codex locate commands within a plugin?

The Codex runtime scans the plugin's `commands/` directory for all files matching the pattern `*.md`. Each discovered file is parsed to extract its front-matter and structured sections, building an internal registry that maps command names (derived from filenames) to their specifications. This process happens at plugin load time, making commands immediately available for invocation.

### What is the purpose of the _conventions.md file?

The [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md) file serves as the **authoring guide** for plugin developers, specifying the required sections (Preflight, Plan, Commands, Verification, Result) and formatting standards that every command file must follow. Located at [`plugins/zoom/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/_conventions.md) in the reference implementation, it ensures consistency across all commands within a plugin and across different plugins in the repository.

### Do command files contain executable code?

No. Command files contain **pure documentation** describing workflows and expected outcomes. The actual executable actions—such as API calls, SDK method invocations, or file modifications—are performed by the Codex agent that interprets the command definition. This separation of documentation from execution ensures commands remain auditable, version-controllable, and language-agnostic.