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

> Explore the openai/plugins repository. Learn to build, package, and publish plugins for the Codex platform with this comprehensive guide to Codex plugin development.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: getting-started
- Published: 2026-06-22

---

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

```json
{
  "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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) file contains UI-specific configuration such as screenshots, extended descriptions, and marketplace categorization. When combined with the `interface` section of [`plugin.json`](https://github.com/openai/plugins/blob/main/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

```javascript
// 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

```yaml

# .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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md), which generates a new plugin directory with the proper manifest and folder structure.

### Invoking Skills Programmatically

```javascript
// 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) and optional [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files.
- Developers can scaffold new plugins using the built-in `plugin-creator` skill located at [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.