What Is the Purpose of the OpenAI Plugins Repository? A Complete Guide to Codex Plugin Development

The openai/plugins repository is a curated collection of Codex plugin examples that provides reference implementations, scaffolding tools, and best practices for building, packaging, and publishing plugins for the Codex platform.

The openai/plugins repository serves as the official source of truth for developers building extensions for OpenAI's Codex platform. It contains production-grade examples like Figma, Notion, and Mixpanel that demonstrate how to structure plugin manifests, define skills, and prepare packages for the Codex marketplace. Each plugin in the repository follows a standardized architecture that ensures compatibility with the Codex runtime and marketplace.

Core Purpose and Design Goals

The repository fulfills five strategic objectives for the Codex ecosystem:

• Reference Implementation. It provides concrete, production-grade examples (e.g., Figma, Notion, Mixpanel) that illustrate best-practice patterns for plugin structure, manifest fields, and skill definitions.

• Learning and Onboarding. New developers can explore the folder layout, read embedded documentation, and run plugins locally to understand the end-to-end workflow from manifest creation to runtime execution.

• Reusable Building Blocks. Common patterns (such as the plugin-creator skill and asset pipelines) are abstracted into reusable components that other plugins can copy or extend.

• Marketplace Readiness. By adhering to the mandated manifest schema and optional .app.json metadata, each plugin can be published to the Codex marketplace without additional conversion work.

• Community Collaboration. The open-source nature encourages contributions, bug fixes, and new plugin ideas that benefit the broader ecosystem.

Directory Structure and Architecture

Every plugin resides under plugins/<name>/ and follows a strict directory convention that the Codex runtime recognizes.

plugins/
├─ <plugin-name>/
│   ├─ .codex-plugin/
│   │   └─ plugin.json          ← mandatory manifest
│   ├─ .app.json                ← optional UI/marketplace metadata
│   ├─ skills/                  ← skill definitions (Markdown + YAML)
│   ├─ agents/                  ← agent scripts (optional)
│   ├─ commands/                ← CLI commands (optional)
│   └─ assets/                  ← icons, images, etc.

The plugin.json file in .codex-plugin/ is mandatory and defines the plugin's identity, capabilities, and entry points. The optional .app.json supplies UI-specific fields such as branding, screenshots, and default prompts. Skills are Markdown files with YAML front-matter that the Codex runtime parses to expose MCP tools.

The Plugin Manifest Schema

The manifest (plugins/<name>/.codex-plugin/plugin.json) is the authoritative source for plugin metadata. The Figma plugin manifest illustrates the required structure:

{
  "name": "figma",
  "version": "2.0.9",
  "description": "Figma workflows for design implementation, Code Connect templates, and design system rule generation.",
  "author": { "name": "Figma", "url": "https://www.figma.com" },
  "homepage": "https://www.figma.com",
  "repository": "https://github.com/openai/plugins",
  "license": "LicenseRef-Figma-Developer-Terms",
  "keywords": ["figma", "design-to-code", "ui-implementation", "code-connect", "design-system"],
  "skills": "./skills/",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Figma",
    "shortDescription": "Design-to-code workflows powered by the Figma integration",
    "category": "Creativity",
    "capabilities": ["Interactive", "Read", "Write"],
    "websiteURL": "https://www.figma.com",
    "privacyPolicyURL": "https://www.figma.com/legal/privacy/",
    "termsOfServiceURL": "https://www.figma.com/legal/developer-terms/",
    "defaultPrompt": [
      "Inspect a Figma design and implement it in code",
      "Create Code Connect templates for my components",
      "Build or update a screen in Figma"
    ],
    "brandColor": "#1ABCFE",
    "composerIcon": "./assets/logo-padded.png",
    "logo": "./assets/logo-padded.png"
  }
}

Key fields include capabilities (which declares permissions like Interactive, Read, and Write), skills (the relative path to skill definitions), and interface (UI branding and marketplace listing data).

Skill Definitions and MCP Integration

Skills are the functional units of a Codex plugin. Each skill is defined in a SKILL.md file located under plugins/<name>/skills/<skill-name>/.

The figma-use-slides skill in plugins/figma/skills/figma-use-slides/SKILL.md demonstrates the standard format:

• YAML front-matter containing name, description, and disable-model-invocation flags
• Markdown sections detailing usage instructions, design thinking guidelines, and reference links
• MCP tool definitions that the Codex runtime exposes to the language model

When disable-model-invocation is set to false, the Codex runtime can automatically invoke the skill's MCP tools during agent execution.

Scaffolding New Plugins with the Plugin-Creator Skill

The repository includes a meta-skill for generating new plugins. The plugin-creator skill, located at .agents/skills/plugin-creator/SKILL.md, automates the creation of boilerplate directories and manifest files.

When invoked, this skill generates:

1. A new plugins/<plugin-name>/ directory
2. A valid .codex-plugin/plugin.json with populated required fields
3. Standard subdirectories (skills/, assets/, etc.)

This makes the repository a self-referential toolkit: it contains the tools to extend itself.

Practical Implementation Examples

Loading a Manifest in Node.js

To programmatically read a plugin's metadata:

const fs = require('fs');
const path = require('path');

const manifestPath = path.resolve(
  __dirname,
  'plugins/figma/.codex-plugin/plugin.json'
);
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log('Plugin name:', manifest.name);
console.log('Version:', manifest.version);
console.log('Capabilities:', manifest.interface.capabilities);

Configuring an Agent with YAML

Define an agent that uses the plugin-creator skill:

name: plugin-creator
description: Scaffold a new Codex plugin
model: gpt-4
skillNames:
  - plugin-creator
parameters:
  pluginName: str
  version: str
  description: str

Invoking a Skill at Runtime

// Pseudocode for an agent invoking the figma-use-slides skill
await codex.runSkill({
  skillName: "figma-use-slides",
  input: {
    action: "create_new_slide",
    title: "Quarterly Results",
    layout: "title-subtitle-chart"
  }
});

Summary

• The openai/plugins repository is a curated library of Codex plugin examples serving as reference implementations and learning resources.
• Each plugin requires a mandatory plugin.json manifest in .codex-plugin/ and optionally includes .app.json for UI metadata.
• Skills are defined in Markdown files with YAML front-matter under skills/, exposing MCP tools to the Codex runtime.
• The plugin-creator skill at .agents/skills/plugin-creator/SKILL.md provides automated scaffolding for new plugins.
• Production examples like Figma, Notion, and Mixpanel demonstrate marketplace-ready patterns for capabilities, asset management, and branding.

Frequently Asked Questions

What is the primary purpose of the openai/plugins repository?

The openai/plugins repository serves as a curated collection of Codex plugin examples that demonstrates how to build, package, and publish plugins for the Codex platform. It provides production-grade reference implementations (such as Figma and Notion) that developers can study to understand manifest schemas, skill definitions, and marketplace requirements.

How do I create a new plugin using the openai/plugins repository?

Use the plugin-creator skill located at .agents/skills/plugin-creator/SKILL.md to scaffold a new plugin automatically. This skill generates the mandatory directory structure, creates a valid .codex-plugin/plugin.json manifest, and populates standard subdirectories like skills/ and assets/, ensuring your plugin follows Codex platform conventions from the start.

What files are required for a valid Codex plugin in the openai/plugins repository?

Every Codex plugin must include a plugin.json file inside a .codex-plugin/ directory. This manifest defines the plugin's name, version, capabilities, skill paths, and author metadata. While optional, you should also include a .app.json file for UI/marketplace metadata, skills/ directory containing SKILL.md files, and an assets/ directory for icons referenced by the manifest.

How do skills work within the openai/plugins ecosystem?

Skills are functional units defined in Markdown files with YAML front-matter (typically under plugins/<name>/skills/). They expose MCP tools to the Codex runtime through the skillNames parameter. The front-matter includes fields like name, description, and disable-model-invocation, which control whether the language model can automatically invoke the skill during agent execution.

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