# Best Practices for Organizing Plugin Files and Directories in OpenAI Plugins

> Discover best practices for organizing OpenAI plugin files and directories. Ensure automatic discovery and seamless execution with a self-contained module structure including plugin.json and skills/.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-07-05

---

**Organize every OpenAI plugin as a self-contained module under `plugins/<name>/` containing a mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, a `skills/` directory with [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry points, and optional configuration files to ensure automatic discovery by the marketplace loader and seamless execution by the Codex runtime.**

The OpenAI Plugins repository enforces a strict modular architecture that keeps each integration isolated, versionable, and discoverable. Whether you are scaffolding a new capability or refactoring an existing one, following the standardized directory layout guarantees that the Codex runtime can locate entry points and the marketplace loader can expose your plugin to the ecosystem. This guide references the actual source structure from the `openai/plugins` repository, including specific file paths and validation rules extracted from the codebase.

## Core Directory Structure

The repository expects every plugin to live as an independent unit under the top-level `plugins/` directory. This isolation prevents path collisions and allows the marketplace loader to enumerate available capabilities without parsing monolithic configuration files.

### Top-Level Plugin Folders

Each plugin must reside in its own folder under `plugins/<plugin-name>/` using lower-case kebab-case naming (e.g., `my-awesome-plugin`). According to the repository README, this convention guarantees a predictable path for the marketplace loader and maintains strict isolation between plugins. The folder name must match the `"name"` field declared in the plugin manifest to ensure consistency across URLs and identifier systems.

### The Mandatory Manifest File

Every plugin must contain a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file that serves as the single source of truth for the Codex runtime. This manifest defines the plugin's name, version, capabilities, entry points, and interface metadata.

In [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json), the manifest declares:

```json
{
  "name": "figma",
  "version": "2.0.12",
  "description": "Figma design tool integration",
  "skills": "./skills/",
  "interface": {
    "displayName": "Figma",
    "shortDescription": "Access and modify Figma files",
    "category": "Design",
    "capabilities": ["Read", "Write"]
  }
}

```

The `"skills"` key points to the directory containing executable capabilities, while the `"interface"` block provides metadata for the marketplace UI.

## Organizing Skills and Assets

Skills represent discrete capabilities within a plugin, and the repository mandates a specific layout to ensure the runtime can locate entry points and supporting documentation.

### Skills Directory Structure

Inside a plugin, all skills must live under `skills/<skill-name>/` with a mandatory [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry point. This markdown file defines the skill's description, prompts, references, and examples. The runtime loads [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) as the primary interface for executing the skill.

A standard skill layout includes:

- [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) – The executable entry point containing prompts and instructions
- `references/` – API specifications and technical documentation
- `examples/` – Sample interactions and usage patterns
- `scripts/` – Helper scripts for complex operations

For example, the Figma plugin implements [`plugins/figma/skills/figma-use/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-use/SKILL.md) as its primary interaction surface, with supporting files organized in adjacent subdirectories.

### Optional Configuration Files

Plugins remain lightweight by only including necessary configuration files. The repository recognizes several optional surfaces:

- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** – Application-specific settings read by the Codex runtime when present
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** – Multi-customer configuration for enterprise deployments
- **`assets/`** – Self-contained icons, logos, and UI resources referenced by the manifest
- **`commands/`** – CLI commands exposed by the plugin

The Figma plugin demonstrates this pattern by shipping a [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) alongside `assets/logo-padded.png`, which the manifest references directly via `"logo": "./assets/logo-padded.png"`. This self-containment ensures the plugin packages without external resource lookups.

## Registering and Scaffolding Plugins

Integration into the Codex ecosystem requires registration in the central marketplace and adherence to naming conventions during creation.

### Marketplace Registration

Plugins must be enumerated in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) to appear in the Codex marketplace. Each entry maps the plugin name to its local path and defines installation policies:

```json
{
  "name": "figma",
  "source": {
    "source": "local",
    "path": "./plugins/figma"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Design"
}

```

The marketplace loader reads this file at runtime to expose plugins to the ecosystem. When adding a new plugin, submit a pull request updating this JSON file with your plugin's metadata and source path.

### Using the Plugin Creator Script

The repository ships a scaffolding utility at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) that generates the required directory structure and boilerplate files automatically. This script enforces naming conventions and reduces configuration errors.

Generate a new plugin from the repository root:

```bash
python .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    --name my-awesome-plugin \
    --description "An example plugin that does X" \
    --author "Your Name"

```

This creates the following structure:

```

plugins/my-awesome-plugin/
├── .codex-plugin/
│   └── plugin.json
├── assets/
│   └── logo.png
├── skills/
│   └── example/
│       └── SKILL.md
└── README.md

```

Always bump the `"version"` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) whenever the plugin's public API changes, allowing downstream users to pin or upgrade safely.

## Summary

- **Isolate each plugin** under `plugins/<kebab-case-name>/` to ensure predictable paths and avoid collisions
- **Provide a complete manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with accurate version, skills path, and interface metadata
- **Structure skills** under `skills/<name>/` with a mandatory [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry point and optional `references/`, `examples/`, or `scripts/` subdirectories
- **Include optional files** ([`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), `assets/`) only when needed to keep plugins lightweight
- **Register in marketplace.json** at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) to enable discovery
- **Use the creator script** [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) to scaffold new plugins with correct conventions

## Frequently Asked Questions

### What happens if I don't include a plugin.json manifest?

The Codex runtime cannot load your plugin without the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest. This file is mandatory because it defines the entry points, version, and capabilities required for execution. Without it, the marketplace loader will skip your plugin during enumeration, and the runtime will fail to resolve skill paths.

### Can I organize multiple skills in subdirectories within the skills folder?

Yes, the skills directory supports nested organization. Create subdirectories under `skills/` for each discrete capability, and place a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file at the root of each subdirectory. The runtime discovers these entry points recursively, and you can reference supporting materials in `references/` or `examples/` folders adjacent to each [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md).

### How do I handle versioning when updating my plugin?

Update the `"version"` field in your [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file following semantic versioning principles. The marketplace loader and Codex runtime use this field to manage dependencies and cache invalidation. When submitting updates to the repository, ensure the version bump reflects breaking changes, new features, or patch fixes accordingly.

### Are there naming restrictions for plugin folders and files?

Yes, use lower-case kebab-case for all folder names and manifest `"name"` fields (e.g., `my-awesome-plugin`, not `MyAwesomePlugin` or `my_awesome_plugin`). This convention maintains consistency across filesystems, URLs, and JSON identifiers. The repository README and scaffolding scripts enforce this style to prevent cross-platform path issues.