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

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

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

## 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 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 file (visible in 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 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 in each plugin directory serves as a human-readable catalog. As seen in 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:

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 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, 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 and skill definitions in 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 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 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 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.

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