What Are Slash-Style Command Stubs in OpenAI Plugins?

Slash-style command stubs are declarative markdown files that define deterministic, user-triggered commands in the openai/plugins framework, enabling chat interfaces to expose structured actions via the /command-name syntax.

In the OpenAI Plugins repository, these stubs serve as the single source of truth for slash command behavior. Each file resides in a plugin’s commands/ directory and acts as a contract between the user interface and the plugin’s execution logic.

Anatomy of a Slash-Style Command Stub

File Location and Naming Convention

Every stub lives at plugins/<plugin-name>/commands/<slug>.md. The file name directly determines the invocation syntax; for example, plugins/zoom/commands/setup-zoom-oauth.md automatically registers as the /setup-zoom-oauth command. This convention is enforced by the framework’s file system scanner, as documented in plugins/zoom/commands/_conventions.md.

Required Metadata Sections

Each stub must contain standardized markdown headings that the parser extracts during plugin initialization:

• ## Name – The exact slash command string (e.g., /setup-zoom-oauth)

• ## Description – A concise explanation of the command’s purpose

• ## Arguments – A structured list of parameters, their types, and whether they are required

• ## Example – A sample invocation showing expected user input and bot response

These sections allow the Codex framework to generate the plugin manifest and validate incoming requests without additional code.

How Slash-Style Command Stubs Work

Automatic Discovery and Registration

When a plugin loads, the framework recursively scans the commands/ directory. It parses each markdown file, extracts the metadata sections, and registers the command in the plugin manifest (typically reflected in files like /.agents/plugins/marketplace.json). This process requires no manual registration or boilerplate code in the plugin’s main logic.

From Stub to Execution

Upon invocation, the slash command bypasses open-ended language model routing. The framework maps the command to its corresponding webhook endpoint—often a bot_notification handler described in plugins/zoom/skills/team-chat/concepts/webhooks.md—and passes the arguments as a structured JSON payload. This deterministic flow ensures consistent behavior for setup, diagnostic, and configuration tasks.

Practical Examples

Simple Greeting Command

Create plugins/example/commands/hello.md:

## Name

/hello

## Description

Greets the user with a friendly message.

## Arguments

None

## Example

User: `/hello`
Bot: "Hello, {user_name}! How can I help you today?"

When deployed, typing /hello in the chat interface triggers this command and returns the templated response.

Complex OAuth Setup Command

The Zoom plugin defines plugins/zoom/commands/setup-zoom-oauth.md for guided authentication:

## Name

/setup-zoom-oauth

## Description

Guides the user through the OAuth flow required for Zoom API access.

## Arguments

- `client_id` (string) – Your Zoom app's client ID.
- `client_secret` (string) – Your Zoom app's client secret.

## Example

User: `/setup-zoom-oauth client_id=ABC123 client_secret=XYZ789`
Bot: "I've stored your credentials and will now generate the redirect URL..."

This stub defines two required string arguments. The UI enforces these inputs before sending the payload to the plugin’s webhook.

Chat Invocation

User: /setup-zoom-oauth client_id=ABC123 client_secret=XYZ789

Bot: ✅ Credentials received. Redirecting to Zoom authorization...

Summary

• Slash-style command stubs are markdown files stored in plugins/<name>/commands/ that declare deterministic chat commands.
• File naming determines the command path; setup-zoom-oauth.md becomes /setup-zoom-oauth.
• Standardized sections (Name, Description, Arguments, Example) enable automatic parsing and manifest generation.
• Zero registration code is required; the framework discovers stubs automatically during plugin load.
• Execution routes directly to defined webhooks, bypassing probabilistic language model routing for reliable operational workflows.

Frequently Asked Questions

What is the difference between slash commands and open-ended chat routing?

Slash commands provide deterministic execution paths for specific operational tasks like configuration or diagnostics, routing directly to defined endpoints. Open-ended chat routing relies on the language model to interpret user intent probabilistically, which is better suited for general conversation rather than structured operations.

How do I validate arguments in a slash-style command stub?

Argument validation is handled by the ## Arguments section schema. The framework parses this section to enforce type checking and required field presence before invoking the webhook. Complex validation logic should be implemented in the receiving endpoint code, not the stub itself.

Can a plugin have multiple slash-style command stubs?

Yes. A plugin can contain any number of stub files in its commands/ directory. Each file creates a distinct /command-name entry point, allowing plugins to expose comprehensive management interfaces without cluttering the conversational interface.

Where are slash-style command stubs registered in the plugin manifest?

During the build process, the framework aggregates all discovered stubs into the plugin manifest, visible in files such as /.agents/plugins/marketplace.json. This manifest lists available commands, their descriptions, and argument schemas for the host application to consume.

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