How to Configure Default Prompts for Better User Onboarding in OpenAI Plugins

To configure default prompts for better user onboarding in OpenAI Plugins, add a defaultPrompt field to the plugin.json file located in the .codex-plugin directory, using either a single string or an array of strings to define starter suggestions that appear in the UI.

The openai/plugins repository provides reference implementations for building ChatGPT plugins that integrate with external APIs. Configuring default prompts for better user onboarding in plugins ensures that first-time users immediately understand a plugin's capabilities through pre-populated suggestion chips, reducing the cognitive load required to craft initial queries.

Understanding the Default Prompt Schema

In the openai/plugins architecture, each plugin defines its metadata in a plugin.json file stored within the hidden .codex-plugin directory. The defaultPrompt field accepts either a single string or an array of strings, which the Codex runtime parses and injects into the user interface as clickable starter suggestions.

When the runtime loads the plugin configuration, it checks for the presence of defaultPrompt. If found, these strings populate the UI as quick-start options, allowing users to trigger common workflows without typing custom queries.

Real-World Examples from the Repository

The following examples demonstrate how different plugins implement default prompts to guide user onboarding.

Zoom Plugin (Array of Strings)

The Zoom plugin uses an array to offer multiple entry points for scheduling and meeting management. Located at plugins/zoom/.codex-plugin/plugin.json:

{
  "type": "plugin",
  "name": "Zoom",
  "shortDescription": "Interact with Zoom meetings and recordings",
  "longDescription": "Zoom plugin provides capabilities ...",
  "defaultPrompt": [
    "Schedule a Zoom meeting for tomorrow at 3pm.",
    "List all upcoming Zoom meetings."
  ],
  "config": {}
}

Notion Plugin (Single String)

The Notion plugin demonstrates using a single descriptive string that encompasses multiple actions. Found in plugins/notion/.codex-plugin/plugin.json:

{
  "type": "plugin",
  "name": "Notion",
  "shortDescription": "Interact with Notion pages and databases",
  "longDescription": "Notion plugin lets you read, update, and create pages ...",
  "defaultPrompt": "Search Notion workspace content, update pages, or turn specs, notes, and meeting context into structured outputs",
  "config": {}
}

Temporal Plugin (Concise Array)

The Temporal plugin provides a focused workflow creation prompt. Located at plugins/temporal/.codex-plugin/plugin.json:

{
  "type": "plugin",
  "name": "Temporal",
  "shortDescription": "Workflow orchestration",
  "longDescription": "Temporal plugin allows creating and managing workflows ...",
  "defaultPrompt": ["Create a workflow using Temporal."],
  "config": {}
}

Step-by-Step Configuration Guide

Follow these steps to configure default prompts for better user onboarding in your plugin.

Locate the Plugin Configuration File

Navigate to your plugin's .codex-plugin directory and open plugin.json. This file serves as the single source of truth for plugin metadata and onboarding configuration.

Define Your Default Prompts

Add the defaultPrompt field at the root level of the JSON object. Use an array when offering multiple distinct actions, or a single string for a unified description of capabilities.

Example with multiple specific prompts:

{
  "defaultPrompt": [
    "Schedule a Zoom meeting for tomorrow at 3pm with the sales team.",
    "List all upcoming Zoom meetings for the next 7 days.",
    "Download the recording of the last Zoom meeting titled 'Project Kickoff'."
  ]
}

Validate JSON Structure

Ensure your plugin.json follows valid JSON syntax. The defaultPrompt field must contain either:

• A JSON string (e.g., "Search content...")
• An array of strings (e.g., ["Prompt 1", "Prompt 2"])

Version Control and Deploy

Commit your changes to track iterations of your onboarding strategy:

git add plugins/your-plugin/.codex-plugin/plugin.json
git commit -m "Add default prompts for improved user onboarding"

Best Practices for Effective Onboarding Prompts

To maximize the impact of your default prompts:

• Be specific and outcome-oriented: Include concrete details like dates, participants, or file names to reduce ambiguity.
• Keep prompts under 120 characters: Shorter strings display better in UI chips and remain readable.
• Cover high-value use cases: Prioritize the 2-3 most common actions users take with your plugin.
• Iterate based on usage: Review which prompts users click most frequently and refine underperforming suggestions.

Summary

• The defaultPrompt field in plugin.json controls which starter suggestions appear when users first interact with a plugin.
• Location: Store configuration in plugins/<plugin-name>/.codex-plugin/plugin.json.
• Format: Accepts either a single string or an array of strings.
• Examples: Zoom uses multiple prompts, Notion uses a single descriptive string, and Temporal uses a concise array.
• Best practices: Write specific, short prompts that cover primary use cases and version control changes.

Frequently Asked Questions

Can I use variables or dynamic content in default prompts?

No, the defaultPrompt field only supports static strings according to the openai/plugins source code. The runtime treats these as literal text suggestions that appear in the UI. For dynamic content, implement custom frontend logic that queries your API after the user selects a default prompt template.

How many default prompts should I include?

Include 2-4 prompts for optimal user experience. The Zoom plugin demonstrates this with two distinct actions (scheduling and listing), while the Temporal plugin uses a single focused prompt. Adding more than four can overwhelm new users and reduce the likelihood of any single prompt being selected.

Why does my plugin not show the default prompts in the UI?

First, verify that your plugin.json is located in the .codex-plugin directory and contains valid JSON with the defaultPrompt field properly spelled. Second, ensure the Codex runtime has reloaded the plugin configuration; changes may require a restart or cache refresh depending on your deployment environment.

Can I localize default prompts for different languages?

The current schema in openai/plugins supports only a single defaultPrompt field without built-in localization keys. To support multiple languages, you would need to implement a custom localization layer that selects the appropriate prompt string based on user locale before the runtime loads the plugin.json, or maintain separate plugin configurations for different regions.

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