How to Add Default Prompts to OpenAI Plugins

OpenAI plugins expose a defaultPrompt array inside the interface section of each plugin's manifest file (plugin.json), and the Codex UI automatically surfaces these prompts to users without requiring any runtime code changes.

The openai/plugins repository uses a manifest-driven architecture where starter prompts are defined declaratively in JSON configuration files. Adding default prompts helps users understand your plugin's capabilities and provides concrete entry points for conversation. This guide covers the exact file locations, JSON schema requirements, and implementation patterns used across the official plugin ecosystem.

Locating the Plugin Manifest File

Each plugin stores its configuration in a standardized location within the repository structure. The manifest file resides at:

plugins/<plugin-name>/.codex-plugin/plugin.json

For example, the Zoom plugin manifest is located at plugins/zoom/.codex-plugin/plugin.json, while the Superpowers plugin uses plugins/superpowers/.codex-plugin/plugin.json. This consistent path structure applies to all plugins in the repository, including Temporal, Notion, and Outlook Calendar.

Configuring the defaultPrompt Array

The defaultPrompt field is optional and resides inside the interface object. When present, it must contain a JSON array of strings, where each string represents a short, self-contained instruction that the plugin can handle out-of-the-box.

The Codex runtime reads the plugin.json at load time and injects any defaultPrompt entries into the UI's prompt-suggestion component. No additional runtime code changes are required; the manifest drives the behavior entirely.

JSON Schema Requirements

• Location: interface.defaultPrompt
• Type: Array of strings
• Optional: Yes (omitting the field means no starter prompts appear)
• Content: Each string should be a concrete, actionable prompt a user might send to the plugin

Example Configurations

Adding Prompts to the Zoom Plugin

The Zoom plugin already implements defaultPrompt at lines 43-45 of its manifest. You can follow this pattern by adding your prompts to the array:

{
  "interface": {
    "displayName": "Zoom",
    "shortDescription": "Use Zoom meeting context and build Zoom integrations.",
    "longDescription": "...",
    "defaultPrompt": [
      "Search my recent Zoom meetings for the discussion about pricing.",
      "Run /plan-zoom-product for a Zoom integration idea."
    ],
    "brandColor": "#0B5CFF"
  }
}

According to the openai/plugins source code, these prompts appear as clickable suggestions when users interact with the Zoom plugin in the Codex UI.

Creating Prompts for a New Plugin

When building a new plugin from scratch, include the defaultPrompt array in your initial plugin.json:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Example plugin",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Demo of default prompts",
    "longDescription": "A simple example showing how to surface starter prompts.",
    "defaultPrompt": [
      "Summarize the latest data from My API.",
      "Create a new resource using the default settings."
    ]
  },
  "skills": "./skills/"
}

After committing this file to plugins/my-plugin/.codex-plugin/plugin.json, the two prompts automatically appear in the Codex UI for your plugin.

Updating Existing Plugin Prompts

To modify prompts for an existing plugin like Superpowers, edit the manifest at plugins/superpowers/.codex-plugin/plugin.json:

{
  "interface": {
    "defaultPrompt": [
      "Generate a new superhero character with powers.",
      "Show me the last three saved game states."
    ]
  }
}

Other plugins in the repository demonstrate this pattern:

• Temporal: "Create a workflow using Temporal."
• Notion: "Search Notion workspace content, update pages, or turn specs, notes, and meeting context into structured outputs"
• Outlook Calendar: "Summarize my day, compare availability, explain Outlook status, and draft the right event update"

How the Codex Runtime Processes Default Prompts

The Codex runtime implements a manifest-driven loading system. When the system initializes a plugin, it parses the plugin.json file and extracts the interface.defaultPrompt array. These values are injected directly into the UI's prompt-suggestion component, making them available to users immediately upon loading the plugin interface.

This architectural approach means:

• No runtime deployment is required to update prompts
• No code compilation is necessary after editing the JSON
• Changes are immediate once the manifest file is committed

Summary

• File location: Edit plugins/<plugin-name>/.codex-plugin/plugin.json to configure default prompts
• Field path: Add the defaultPrompt array inside the interface object
• Data format: Use a JSON array of strings, where each string is a concrete user prompt
• Runtime behavior: The Codex UI reads these values at load time and surfaces them as clickable suggestions
• Optional field: Omitting defaultPrompt simply results in no starter prompts being displayed

Frequently Asked Questions

What is the exact file path for adding default prompts to a plugin?

The manifest file is located at plugins/<plugin-name>/.codex-plugin/plugin.json. For example, the Zoom plugin uses plugins/zoom/.codex-plugin/plugin.json, and the Superpowers plugin uses plugins/superpowers/.codex-plugin/plugin.json.

Do I need to restart the Codex runtime after adding default prompts?

No. The Codex runtime reads the plugin.json manifest at load time and injects the defaultPrompt values into the UI automatically. Since this is a configuration-driven architecture, no runtime code changes or restarts are required after editing the JSON file.

What happens if I omit the defaultPrompt field from the plugin.json?

The defaultPrompt field is optional. If you omit it or leave the array empty, the plugin will simply not display any starter prompts in the Codex UI. The plugin will still function normally; users will just need to initiate conversations without suggested prompts.

Can I include variables or dynamic content in default prompts?

No. The defaultPrompt array only accepts static strings. Each entry should be a complete, self-contained instruction that requires no additional context or runtime substitution to be meaningful to the user.

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