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

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

The OpenAI plugins repository serves as the official reference implementation and learning resource for developers building on the Codex platform. According to the repository's top-level README (located at README.md), it contains a curated collection of Codex plugin examples—including integrations for Figma, Notion, and Mixpanel—that illustrate best practices for plugin architecture and marketplace readiness. The repository functions as a living library of patterns, providing concrete implementations that developers can study, copy, and extend.

Core Purpose and Design Goals

The OpenAI plugins repository fulfills five strategic objectives that guide its structure and content:

• 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 & 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) 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.

Repository Structure and Architecture

The OpenAI plugins repository enforces a strict directory convention that the Codex runtime expects when loading extensions.

Directory Layout

Each plugin lives under plugins/<name>/ and follows a standardized structure:

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 file at .codex-plugin/plugin.json defines the plugin's identity, version, and capabilities, while the skills/ directory contains Markdown files with YAML frontmatter that register functionality with the Codex runtime.

The Mandatory Manifest Schema

Every plugin must include a plugin.json file that declares metadata consumed by the marketplace and runtime. The Figma plugin (version 2.0.9) demonstrates the complete schema:

{
  "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"
  }
}

This file is located at plugins/figma/.codex-plugin/plugin.json and serves as the authoritative source for plugin metadata, including the capabilities array that declares whether the plugin supports "Interactive", "Read", or "Write" operations.

Skill Definitions and Agent Configuration

Skills are the functional units of a Codex plugin, defined in Markdown files with YAML frontmatter that the runtime parses to expose MCP tools.

Skill File Structure

For example, the figma-use-slides skill (located at plugins/figma/skills/figma-use-slides/SKILL.md) introduces Slides-specific rules and usage patterns. Key elements include:

• name – The identifier used when invoking the skill.
• description – Short prose shown in the marketplace.
• disable-model-invocation – A flag controlling whether the language model can call the skill automatically.
• Sections – Detailed usage instructions, design thinking guidelines, and reference links.

The repository also includes a plugin-creator skill at .agents/skills/plugin-creator/SKILL.md that generates scaffolding for new plugins, demonstrating how developers can programmatically produce compliant plugin bundles.

Asset Management and Marketplace Metadata

Visual assets and UI metadata are stored separately from code but referenced by the manifest:

• Assets – Icons and images reside in assets/ and are referenced via relative paths (e.g., "composerIcon": "./assets/logo-padded.png").
• .app.json – This optional file supplies UI-specific fields such as branding, screenshots, and default prompts shown to users in the marketplace interface.

Practical Implementation Examples

Loading a Plugin Manifest

The following Node.js example demonstrates how a runtime or build tool can read the mandatory manifest:

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

Registering a Skill in a Codex Agent

The plugin-creator skill can be invoked via agent configuration:

# .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 the agent runs, it invokes the plugin-creator skill to generate a new plugin directory with the proper manifest and folder structure.

Invoking Skills Programmatically

Skills are called at runtime by name, as shown in this pseudocode example:

// 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 target API.

Summary

• The OpenAI plugins repository is a curated collection of Codex plugin examples designed for reference, learning, and community collaboration.
• Each plugin requires a mandatory plugin.json manifest under .codex-plugin/ and organizes code into skills/, agents/, commands/, and assets/ directories.
• Skills are defined in Markdown with YAML frontmatter, supporting flags like disable-model-invocation to control runtime behavior.
• The repository includes a plugin-creator skill (located at .agents/skills/plugin-creator/) that automates scaffolding for new plugins.
• Compliance with the manifest schema and optional .app.json metadata ensures plugins are ready for immediate publication to the Codex marketplace.

Frequently Asked Questions

What is the purpose of the OpenAI plugins repository?

The OpenAI plugins repository serves as a reference implementation and learning resource for developers building Codex plugins. It provides production-grade examples (such as Figma and Notion integrations) that demonstrate standardized patterns for manifest structure, skill definitions, and marketplace packaging, enabling developers to build, test, and publish extensions that work seamlessly with the Codex platform.

What files are required for a minimal Codex plugin?

At minimum, a Codex plugin must include 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, and interface capabilities. While optional, most plugins also include a skills/ directory containing Markdown skill definitions and an assets/ folder for icons referenced by the manifest.

How do skill definitions work in Codex plugins?

Skills are defined in Markdown files with YAML frontmatter blocks that specify metadata such as name, description, and disable-model-invocation. The Codex runtime parses these files to expose MCP tools. For example, the Figma plugin's figma-use-slides skill (located at plugins/figma/skills/figma-use-slides/SKILL.md) contains usage rules and parameters that the runtime uses to handle design-to-code workflows.

Can I use the OpenAI plugins repository to create my own plugin?

Yes. The repository includes a plugin-creator skill (found at .agents/skills/plugin-creator/SKILL.md) specifically designed to scaffold new plugins. By invoking this skill with parameters like pluginName and version, developers can generate a complete plugin directory structure with a valid plugin.json manifest and skill templates, ensuring compliance with Codex platform requirements from the start.

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