How Commands/ Directories in Plugins Define CLI‑Style Interactions

The commands/ directory in each OpenAI plugin defines CLI‑style interactions through structured markdown files containing workflow sections, YAML front‑matter metadata for discovery, and executable Python scripts that use argparse subparsers to handle command logic.

The openai/plugins repository implements a declarative architecture where user‑invoked slash commands are self‑contained documents stored in plugins/*/commands/ paths. This convention enables the Codex runtime to orchestrate reproducible workflows by parsing markdown command definitions and delegating low‑level operations to Python helpers.

Markdown Command Definitions with Structured Sections

Every user‑facing command lives as a .md file inside the commands/ folder. These files follow a strict layout enforced by the repository‑wide convention file located at plugins/zoom/commands/_conventions.md. Each command must declare six standardized sections that Codex reads sequentially:

• Preflight – Environment checks and prerequisites
• Plan – Statement of intent for the operation
• Commands – The actual CLI instructions or tool invocations
• Verification – Assertions to confirm success
• Summary – Structured result output
• Next Steps – Follow‑up actions or conditional branches

This consistent ordering allows the platform to generate deterministic prompts and responses across all plugins. The _conventions.md file also mandates safety rules, such as prohibiting the printing of secret values, ensuring uniform behavior regardless of the specific plugin domain.

Front‑Matter Metadata for Discovery

Each markdown file begins with a YAML front‑matter block that exposes metadata for the platform’s indexing and UI tooltips. At minimum, the block must provide a description field that summarizes the command’s purpose for discovery interfaces.

For example, plugins/zoom/commands/plan-zoom-integration.md starts with front‑matter defining the command’s tooltip text before the structured workflow sections begin. This metadata is parsed during plugin loading to populate command palettes and help menus without requiring the platform to execute the full document.

Executable CLI Logic in Python Scripts

While markdown files declare the workflow, the actual computational work is performed by Python scripts that expose CLI‑style interfaces via argparse. The convention requires creating a subparser structure using parser.add_subparsers(dest="command", required=True), then registering each concrete verb with subcommands.add_parser(...).

The zotero.py script at plugins/zotero/skills/zotero/scripts/zotero.py (line 730) demonstrates this pattern. It constructs a base argument parser, adds subparsers for commands like status, enable, and disable, and defines arguments with add_argument(). When a slash command requires low‑level file inspection or API calls, the runtime spawns the corresponding script, passing parsed arguments obtained from the markdown’s Commands section.

Command Execution Workflow

When a user types a slash command such as /plan‑zoom‑integration, the runtime executes the following sequence:

1. Load – Reads plan‑zoom‑integration.md and validates it against the _conventions.md schema.
2. Preflight – Executes checks listed in the Preflight section (e.g., verifying environment variables like ZOOM_APP_CLIENT_ID).
3. Invocation – Runs the shell commands or Python scripts specified in the Commands section, passing any flags defined in the document.
4. Verification – Compares the script’s JSON output against the Verification criteria to confirm the intended state change occurred.
5. Rendering – Injects the results into the Summary section and displays Next Steps to the user.

Because the markdown is self‑contained, developers can copy a skeleton file, rename it, and fill in domain‑specific logic without modifying the runtime.

Implementing Custom Commands

Adding Subcommands to Python Helpers

To expose a new CLI verb, extend the existing argparse structure defined in scripts like zotero.py:

import argparse

parser = argparse.ArgumentParser(prog="mytool")
subcommands = parser.add_subparsers(dest="command", required=True)

# Existing commands

subcommands.add_parser("status", help="Show current status")

# New CLI command

new_cmd = subcommands.add_parser(
    "reset",
    help="Reset the plugin's local state"
)
new_cmd.add_argument(
    "--hard",
    action="store_true",
    help="Perform a hard reset (deletes all cached data)"
)

args = parser.parse_args()
if args.command == "reset":
    do_reset(hard=args.hard)

This pattern matches the implementation in plugins/zotero/skills/zotero/scripts/zotero.py.

Creating the Markdown Command Skeleton

A minimal command file combining front‑matter and workflow sections looks like this:

---
description: Show the current Zoom integration status
---

# Zoom Integration Status

## Preflight

- Verify the repository contains a Zoom app manifest.
- Ensure `ZOOM_APP_CLIENT_ID` is defined in the environment.

## Plan

State that we will read the manifest and print the client ID.

## Commands

```text
zoom-cli status

Verification

• Confirm the client ID matches the value from the manifest.
• Output the version reported by the Zoom SDK.

Summary

## Result

- Action: read Zoom manifest
- Status: success
- Details: client_id=XYZ123

Next Steps

• Run /debug-zoom if the SDK version is out‑of‑date.

Key files supporting this architecture include:
- [`plugins/zoom/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/_conventions.md) – Central definition of required markdown sections and safety rules
- [`plugins/zoom/commands/plan-zoom-integration.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/plan-zoom-integration.md) – Concrete example of a user‑facing command following the convention
- [`plugins/zotero/skills/zotero/scripts/zotero.py`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/scripts/zotero.py) – Reference implementation of `argparse` subparsers for CLI logic
- `plugins/*/commands/*.md` – Individual command definitions across the repository

## Summary

- The `commands/` directory uses **structured markdown files** with six mandatory sections (Preflight, Plan, Commands, Verification, Summary, Next Steps) to declare reproducible workflows.
- **YAML front‑matter** in each file provides metadata for command discovery and UI tooltips.
- **Python scripts** utilizing `argparse.add_subparsers()` handle the executable logic, receiving arguments from the markdown and returning JSON for verification.
- The [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md) file enforces safety standards and consistent formatting across all plugins in the openai/plugins repository.
- This architecture separates human‑readable intent (markdown) from machine execution (Python), enabling reliable CLI‑style interactions through slash commands.

## Frequently Asked Questions

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

According to the [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md) file in `plugins/zoom/commands/`, every command must include **Preflight**, **Plan**, **Commands**, **Verification**, **Summary**, and **Next Steps** sections in that exact order. This structure ensures Codex can parse the document deterministically and execute safety checks before running destructive operations.

### How does the Codex runtime parse command arguments?

The runtime delegates argument parsing to Python scripts that use the standard `argparse` module. Specifically, scripts like [`zotero.py`](https://github.com/openai/plugins/blob/main/zotero.py) create a subparser hierarchy with `parser.add_subparsers(dest="command", required=True)` and register each verb via `subcommands.add_parser()`. When the markdown **Commands** section specifies a particular sub‑command, the runtime invokes the script with those arguments and captures the stdout for the **Verification** step.

### Can plugin commands access sensitive environment variables?

Yes, but strict conventions apply. The **Preflight** section typically checks for variables like `ZOOM_APP_CLIENT_ID`, and the [`_conventions.md`](https://github.com/openai/plugins/blob/main/_conventions.md) explicitly forbids commands from printing secret values in any output section. This ensures credentials can be used for API calls but are never exposed in logs or rendered back to the user interface.

### Where are safety conventions defined for all plugin commands?

Safety rules and section ordering requirements are defined in the hidden file [`plugins/zoom/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/commands/_conventions.md). This file acts as the schema validator for the entire repository, ensuring every command includes hazard checks (such as "Never print secret values") and maintains predictable output formatting across different plugin implementations.

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