How to Create Plugin-Level Commands in OpenAI Plugins

Plugin-level commands in OpenAI Plugins are self-contained markdown files stored in a commands/ directory that follow strict conventions defined in _conventions.md, allowing Codex to execute reusable actions like OAuth setup or debugging workflows.

The OpenAI Plugins repository enables developers to define reusable, verifiable actions through structured markdown documents. Each plugin maintains its own set of commands that Codex can parse and execute directly. Creating a valid plugin-level command requires understanding the specific directory structure and mandatory sections enforced by the repository's conventions.

Command Architecture and Conventions

Every plugin-level command must adhere to the Command Conventions defined in the plugin's _conventions.md file. These conventions standardize how commands describe their intent, validate prerequisites, and execute operations.

Required Directory Structure

Commands reside in a dedicated commands/ folder inside the plugin directory. For example, the Zoom plugin stores its commands at plugins/zoom/commands/. The repository recognizes any markdown file in this directory—excluding files with leading underscores—as a potential command.

Standardized Sections

Each command file must contain specific sections that Codex parses to understand and execute the workflow:

• Front-matter: A YAML block at the top of the file containing at minimum a description field that surfaces the command in the Codex UI.
• Preflight: Validation checks that verify required tools, credentials, or existing code before execution.
• Plan: A declaration of intended changes, including which files will be modified and any destructive steps requiring confirmation.
• Commands: The executable core presented as a numbered list of concrete steps (file edits, environment variable additions, etc.).
• Verification: Steps to confirm successful execution by re-reading changed files or validating runtime state.
• Summary: A result block in a plain text fenced code block that Codex displays after execution.
• Next Steps: Optional guidance for follow-up actions.

Creating a New Plugin-Level Command

To implement a functional command, create a markdown file in the appropriate commands/ directory and populate the required sections.

Minimal Command Template

The following skeleton demonstrates the exact structure required for a new command file:

---
description: Perform a sample action for MyPlugin.
---

# My Plugin Action

## Preflight

1. Verify that the repository contains a `my-plugin/` directory.
2. Confirm the presence of required tooling (e.g., `node`, `npm`).

## Plan

- Edit `my-plugin/config.yaml` to add a new feature flag.
- Update `my-plugin/.env.example` with the new variable name.

## Commands

1. Open `my-plugin/config.yaml` and insert `feature_enabled: true`.
2. Append `FEATURE_ENABLED=true` to `my-plugin/.env.example`.

## Verification

- Re-open `my-plugin/config.yaml` and confirm the line exists.
- Search `my-plugin/.env.example` for `FEATURE_ENABLED`.

## Summary

```text

## Result

- Action: added feature flag
- Status: success
- Details: modified config.yaml and .env.example

Next Steps

• Run npm run build for MyPlugin to ensure the flag is picked up.

**Critical requirement**: The **Summary** section must use a plain text fenced code block (specified as ```text) rather than syntax-highlighted code blocks to match the repository convention.

## Real-World Implementation Examples

The Zoom plugin provides production-ready examples demonstrating these conventions in practice.

**[`plugins/zoom/commands/setup-zoom-oauth.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/setup-zoom-oauth.md)** implements a complete OAuth configuration workflow, showing how to structure complex multi-step operations with proper preflight checks and verification steps. This file demonstrates the standard for production commands that interact with external APIs.

**[`plugins/zoom/commands/debug-zoom.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/debug-zoom.md)** offers a simpler pattern for diagnostic commands, illustrating how the same section structure applies to troubleshooting workflows.

Both files reference [`plugins/zoom/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/_conventions.md) as their canonical specification source, which defines the exact markdown structure and metadata requirements.

## Registration and Discovery

Codex discovers commands automatically through the plugin manifest located at `plugins/{plugin-name}/.codex-plugin/plugin.json`. This JSON file registers the plugin and its associated commands directory.

If the manifest does not exist, create one with a `commands` entry pointing to the `commands/` folder. Once the markdown file is committed to the repository, Codex recognizes it as an invocable command that users can reference by name.

## Security Considerations

Command files must **never** contain secrets or hardcoded credentials. Instead, reference environment variable names or placeholders. For example, use `ZOOM_CLIENT_ID` rather than the actual OAuth client ID. This ensures commands remain secure when committed to version control while still guiding users through necessary configuration steps.

## Summary

- **Plugin-level commands** are markdown files stored in `commands/` directories within plugin folders.
- Each command must include **Front-matter** (with `description`), **Preflight**, **Plan**, **Commands**, **Verification**, and **Summary** sections as defined in [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md).
- The **Summary** section requires a plain text fenced code block to display execution results properly.
- Commands are discovered via the **plugin manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).
- Never store secrets in command files; reference environment variables instead.

## Frequently Asked Questions

### Where should plugin-level commands be stored?

Store command files in a `commands/` subdirectory within the specific plugin folder. For example, the Zoom plugin keeps its commands at `plugins/zoom/commands/`. Avoid using leading underscores in filenames, as files like [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md) are reserved for metadata and documentation rather than executable commands.

### What sections are required in a command file?

Every command file must contain six mandatory sections: **Front-matter** (YAML with description), **Preflight** (prerequisite checks), **Plan** (change declaration), **Commands** (actionable steps), **Verification** (success confirmation), and **Summary** (result output). An optional **Next Steps** section can provide follow-up guidance. The [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md) file in the commands directory defines the exact formatting requirements for each section.

### How does Codex discover new commands?

Codex automatically discovers commands through the plugin manifest located at `plugins/{plugin-name}/.codex-plugin/plugin.json`. If this manifest is missing, create one with a `commands` entry pointing to the `commands/` directory. Once committed, Codex parses the markdown files and surfaces them in the UI based on the `description` field in the front-matter.

### Can commands contain sensitive credentials?

No. Command files must not contain secrets, API keys, or passwords. Instead, reference environment variable names (such as `ZOOM_CLIENT_ID` or `API_SECRET`) and instruct users to set these values in their environment. This security constraint ensures that committed command files remain safe while still guiding users through necessary authentication workflows.

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