What Is the openai/plugins Repository? A Complete Guide to Codex Plugin Development

The openai/plugins repository is a curated collection of Codex plugin examples that demonstrates how to build, package, and publish plugins for the Codex platform using standardized manifests and skill definitions.

The openai/plugins repository serves as the official reference implementation for developers building on the Codex platform. It contains production-grade plugin examples such as Figma, Notion, and Mixpanel that illustrate best practices for plugin architecture, manifest configuration, and skill development. Each plugin in the repository follows a strict directory structure centered around a mandatory manifest file and optional assets like skills, agents, and UI resources.

Core Purpose and Goals of the openai/plugins Repository

The repository fulfills five strategic objectives for the Codex ecosystem:

• Reference Implementation: 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 to runtime.
• 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.

Architectural Structure and Required Files

Every plugin in the openai/plugins repository follows a standardized directory layout that the Codex runtime recognizes.

Directory Layout Convention

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 manifest (plugin.json) defines the plugin's name, version, description, author, capabilities, and the relative paths to its skills and UI assets. Skills are written in Markdown with a front-matter block that the Codex runtime parses to expose MCP tools. Optional .app.json supplies UI-specific fields such as branding, screenshots, and the default prompt shown to users.

The Plugin Manifest (plugin.json)

The manifest file is the authoritative source for plugin metadata. For example, the Figma plugin manifest at plugins/figma/.codex-plugin/plugin.json contains:

{
  "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 (defining permissions like "Read" and "Write"), skills (pointing to the skills directory), and interface (containing UI branding and marketplace metadata).

Skill Definitions and MCP Integration

Skills are defined in Markdown files with YAML front-matter that registers them with Codex. For instance, the figma-use-slides skill is located at plugins/figma/skills/figma-use-slides/SKILL.md.

Key elements in a skill file include:

• name – Identifier used when invoking the skill.
• description – Short prose shown in the marketplace.
• disable-model-invocation – Flag controlling whether the language model can call the skill automatically.
• Sections – Detailed usage instructions, design thinking guidelines, and reference links to companion markdown files.

The runtime parses these files to expose MCP (Model Context Protocol) tools that agents can invoke programmatically.

Optional UI and Marketplace Metadata

The optional .app.json file contains UI-specific configuration such as screenshots, extended descriptions, and marketplace categorization. When combined with the interface section of plugin.json, these files determine how the plugin appears in the Codex marketplace and within the in-app UI.

Working with Plugin Code Examples

The repository includes practical patterns for loading manifests and invoking skills.

Loading a Plugin Manifest in Node.js

// Load the plugin manifest for the Figma plugin
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);

This pattern demonstrates how a runtime can read the authoritative metadata source located at plugins/<name>/.codex-plugin/plugin.json.

Registering a Skill in a Codex Agent

# .agents/skills/plugin-creator/agents/openai.yaml

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

When executed, this agent configuration invokes the plugin-creator skill defined in .agents/skills/plugin-creator/SKILL.md, which generates a new plugin directory with the proper manifest and folder structure.

Invoking Skills Programmatically

// 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"
  }
});

The skill's documentation in SKILL.md outlines the required parameters and the MCP calls executed on the Figma Slides API.

Extensibility and Plugin Generation

The repository contains a plugin-creator skill at .agents/skills/plugin-creator/SKILL.md that programmatically generates scaffolded plugins. This skill serves as a living template engine, reading its own manifest structure to produce new plugin bundles that adhere to the openai/plugins repository standards. Developers can use this to bootstrap new projects without manually creating the required directory hierarchy or manifest schema.

Summary

• The openai/plugins repository is a curated collection of Codex plugin examples serving as the definitive reference for plugin development.
• Each plugin requires a mandatory manifest at .codex-plugin/plugin.json and optionally includes skills, agents, commands, and UI assets.
• Skills are defined in Markdown files with YAML front-matter located in the skills/ directory, exposing MCP tools to the Codex runtime.
• The repository supports marketplace-ready development through standardized metadata fields in plugin.json and optional .app.json files.
• Developers can scaffold new plugins using the built-in plugin-creator skill located at .agents/skills/plugin-creator/SKILL.md.

Frequently Asked Questions

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

The openai/plugins repository provides a curated collection of Codex plugin examples that serve as reference implementations for developers. It demonstrates how to structure, configure, and package plugins for the Codex platform while providing production-grade examples like Figma and Notion that illustrate best practices for manifest configuration and skill development.

What files are required to create a valid Codex plugin?

Every Codex plugin requires a manifest file located at .codex-plugin/plugin.json within the plugin directory. This JSON file must define the plugin's name, version, description, author, capabilities, and skills path. Optional but recommended files include .app.json for marketplace metadata and assets/ directories for icons and branding resources.

How are skills defined in the openai/plugins repository?

Skills are defined in Markdown files with YAML front-matter blocks, typically stored in plugins/<name>/skills/<skill-name>/SKILL.md. These files specify the skill's name, description, and invocation rules, while the runtime parses them to expose MCP (Model Context Protocol) tools. For example, the Figma plugin's figma-use-slides skill at plugins/figma/skills/figma-use-slides/SKILL.md defines specific capabilities for Figma Slides integration.

Can I use the repository to generate a new plugin template?

Yes. The repository includes a plugin-creator skill located at .agents/skills/plugin-creator/SKILL.md that generates scaffolded plugin directories with the correct structure, manifest templates, and boilerplate files. This skill can be invoked programmatically to create new plugins that automatically conform to the openai/plugins repository standards and manifest schema.

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