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

> Enhance user onboarding in OpenAI Plugins by configuring default prompts within your plugin.json file. Provide starter suggestions for a smoother user experience.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-16

---

**To configure default prompts for better user onboarding in OpenAI Plugins, add a `defaultPrompt` field to the [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json):

```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`](https://github.com/openai/plugins/blob/main/plugins/notion/.codex-plugin/plugin.json):

```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`](https://github.com/openai/plugins/blob/main/plugins/temporal/.codex-plugin/plugin.json):

```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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.