How to Ensure Your OpenAI Plugin Is Discoverable by Users

To ensure your plugin is discoverable by users, you must create a valid .codex-plugin/plugin.json manifest, register your plugin in the .agents/plugins/marketplace.json index, and provide detailed SKILL.md and reference documentation that the discovery engine can index.

The openai/plugins repository implements a structured discovery pipeline that indexes and surfaces plugins to users based on specific metadata conventions. Understanding how this discovery architecture works is essential to ensure your plugin appears in search results and auto-completion suggestions. The system relies on three core components working together to build a searchable catalog of available capabilities.

The Three-Component Discovery Architecture

The discovery engine processes plugins through a specific pipeline that loads metadata from three required locations. Missing any of these components prevents the plugin from appearing in search results.

Plugin Manifest (.codex-plugin/plugin.json)

Every plugin must contain a .codex-plugin/plugin.json file that follows the OpenAI Plugin specification. This manifest declares the plugin's name, description, authentication scheme, API endpoint, and tags that the discovery engine indexes.

The manifest must include these required fields:

• schema_version - Version identifier for the manifest format
• name_for_model - Machine-readable identifier
• description_for_model - Description used by the AI model
• auth - Authentication configuration (type and details)
• api - API specification including OpenAPI URL
• logo_url and contact_email - Branding and support information

Marketplace Index (.agents/plugins/marketplace.json)

The global marketplace file located at .agents/plugins/marketplace.json enumerates all discoverable plugins. This file serves as the entry point for the discovery service; without an entry here, your plugin remains invisible to the system.

When adding a new plugin, insert a JSON entry that maps the plugin's name to its directory path:

{
  "name": "my_plugin",
  "path": "plugins/my-plugin"
}

Skill and Reference Documentation

Inside each plugin folder, the SKILL.md file defines the skill's capabilities, trigger phrases, and input schemas. The references/ sub-directory holds API documentation, example payloads, and auxiliary assets. These files are scanned during the discovery phase to surface fine-grained functionality.

Step-by-Step Implementation Guide

Follow these steps to ensure your plugin is properly indexed and discoverable.

Create the Plugin Manifest

Place a plugin.json file in the .codex-plugin/ directory of your plugin. This example shows the minimal required structure:

{
  "schema_version": "v1",
  "name_for_model": "my_plugin",
  "description_for_model": "A plugin that manages task lists.",
  "auth": {
    "type": "none"
  },
  "api": {
    "type": "openapi",
    "url": "https://my-plugin.example.com/openapi.yaml"
  },
  "logo_url": "https://my-plugin.example.com/logo.png",
  "contact_email": "support@example.com"
}

Register in the Marketplace Index

Edit the .agents/plugins/marketplace.json file to include your plugin. Add an entry that points to your plugin's root directory:

[
  {
    "name": "my_plugin",
    "path": "plugins/my-plugin"
  }
]

The discovery service reads this index at startup and builds a searchable catalog of available plugins.

Document Skills and References

Create a SKILL.md file in your plugin root to describe capabilities:

# My Plugin Skill

description: "Create, list, and delete tasks in a personal todo list."

triggers:
  - "create a task"
  - "show my tasks"
  - "delete task"

input_schema:
  type: object
  properties:
    title:
      type: string
      description: "The task title"
    due_date:
      type: string
      format: date

Populate the references/ directory with API specs and example requests:

## Create Task Endpoint

`POST /tasks`

Request:

```json
{
  "title": "Buy groceries",
  "due_date": "2026-07-10"
}

Response:

{
  "id": "12345",
  "title": "Buy groceries",
  "due_date": "2026-07-10",
  "completed": false
}

## How the Discovery Engine Processes Your Plugin

When the discovery engine runs, it executes a three-phase pipeline:

1. **Index Loading** - The engine loads [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and resolves each plugin's root directory.
2. **Manifest Parsing** - It reads each plugin's [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to extract high-level metadata including name, description, and authentication requirements.
3. **Capability Mapping** - It parses [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) and `references/` files to build a detailed action map of specific functions the plugin can perform.

Only plugins present in the marketplace index and equipped with a valid manifest are shown to end-users.

## Summary

To ensure your OpenAI plugin is discoverable by users:

- **Create a manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with required fields including `schema_version`, `name_for_model`, and `description_for_model`.
- **Register in the marketplace** by adding an entry to [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) that maps your plugin name to its directory path.
- **Provide skill metadata** in a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file describing trigger phrases and input schemas.
- **Supply reference docs** in the `references/` directory with API specs and example payloads.
- **Keep metadata updated** when changing APIs or adding capabilities to maintain synchronization with the discovery cache.

## Frequently Asked Questions

### What happens if I don't register my plugin in marketplace.json?

If your plugin is missing from [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), the discovery service will not resolve your plugin's root directory during the index loading phase. Your plugin will be completely invisible to users and will not appear in search results or auto-completion suggestions, regardless of how well-documented your manifest and skills are.

### Is authentication required in the plugin.json manifest?

Authentication is not strictly required, but you must specify an `auth` field. Use `"type": "none"` for publicly accessible APIs, or specify `oauth`, `api_key`, or other supported authentication schemes for protected endpoints. The discovery engine reads this configuration to determine how to route requests to your API.

### How does the discovery engine use SKILL.md files?

The discovery engine parses [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files to extract trigger phrases, input schemas, and capability descriptions. This enables fine-grained discovery where users can find your plugin not just by name, but by specific actions like "create task" or "list documents." Without this file, the engine can only index high-level metadata from the manifest, limiting discoverability.

### What file format should reference documentation use?

Reference documentation should use Markdown files placed in the `references/` directory. These files should contain structured API documentation, example JSON payloads, and response schemas. The discovery engine scans these files to validate that your plugin can fulfill the advertised actions and to provide detailed context to the AI model.

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