# How to Organize Plugin Directory Structure in the OpenAI Plugins Repository

> Organize your OpenAI plugin directory structure with a root folder plugin.json manifest assets and skills directories. Learn efficient management for the openai plugins repository.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**To organize a plugin directory structure in the OpenAI Plugins repository, create a root folder under `plugins/` containing a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, an `assets/` folder for icons, and a `skills/` directory where each skill contains a mandatory [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry point, keeping all content within three directory levels.**

The OpenAI Plugins repository enforces a strict, opinionated layout that enables Codex to locate assets, skills, and manifests reliably. Understanding how to organize plugin directory structure correctly ensures your plugin appears in the marketplace and loads at runtime. This guide maps the authoritative requirements found in the repository’s root README and contribution guidelines to practical implementation steps.

## Required Top-Level Structure

Every plugin resides in its own directory under the `plugins/` folder. The root of each plugin must follow a specific pattern for the marketplace crawler to recognize it.

According to the repository root README, the canonical layout requires:

```text
plugins/
└─ <plugin-name>/
   ├─ .codex-plugin/
   │   └─ plugin.json
   ├─ assets/
   └─ skills/

```

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file serves as the mandatory manifest describing the plugin’s name, description, entry points, and required scopes. Without this file in the exact location `plugins/<plugin-name>/.codex-plugin/plugin.json`, the marketplace cannot index the plugin.

## Mandatory Files and Their Locations

Three categories of files are strictly required for every plugin submission:

1. **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – The manifest file that powers marketplace discovery. Example: [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) contains the canonical schema.

2. **`skills/<skill-name>/SKILL.md`** – The entry point for each skill. This markdown file must include front-matter with `name` and `description` fields. The Zoom contribution guidelines at [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md) explicitly require this file for every skill directory.

3. **`assets/`** – Contains icons, logos, and static media referenced by the marketplace UI. For example, `plugins/finn/assets/logo.png` follows the expected pattern.

Optional but supported files include [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for UI-only configuration and [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) for Git-hook integrations.

## Organizing Skill Subdirectories

Within each skill directory, maintain a flat hierarchy using specific subfolders to separate concerns:

- **`references/`** – Stores extensive markdown documentation such as API specification tables and troubleshooting guides. The style guide advises moving detailed content here to keep [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) under 500 lines.

- **`agents/`** – Holds YAML files defining LLM-agent policies, such as [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml), which control implicit invocations and tool usage.

- **`scripts/`** – Contains helper Python or Node scripts that implement runtime logic for the skill.

Example structure for a single skill:

```text
skills/<skill-name>/
├─ SKILL.md
├─ references/
│   └─ api-overview.md
├─ agents/
│   └─ openai.yaml
└─ scripts/
    └─ handler.py

```

## Directory Depth Constraints

The repository enforces a strict **three-level depth limit** under any skill directory. This rule appears explicitly in [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md).

Valid paths follow the pattern `skills/<skill-name>/<level-1>/<level-2>/<file>.md`. Exceeding this depth causes build failures and breaks automated tooling traversal. If your documentation requires deeper nesting, flatten the structure by moving files into `references/` or splitting the content into separate top-level skills.

## Complete Plugin Skeleton Example

Below is a minimal skeleton that satisfies all repository validation rules:

```text
plugins/
└─ my-awesome-plugin/
   ├─ .codex-plugin/
   │   └─ plugin.json
   ├─ assets/
   │   └─ icon.png
   ├─ skills/
   │   └─ my-skill/
   │       ├─ SKILL.md
   │       ├─ references/
   │       │   └─ api-overview.md
   │       ├─ agents/
   │       │   └─ openai.yaml
   │       └─ scripts/
   │           └─ handler.py
   └─ .app.json

```

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest must reference the skills and assets correctly:

```json
{
  "name": "my-awesome-plugin",
  "description": "A demo plugin that showcases the required structure.",
  "skills": [
    {
      "name": "my-skill",
      "path": "skills/my-skill"
    }
  ],
  "icon": "assets/icon.png"
}

```

The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file requires YAML front-matter:

```markdown
---
name: my-skill
description: Returns a friendly greeting.
---

# My Skill

This skill demonstrates the minimal structure required.

```

## Common Structure Mistakes to Avoid

Avoid these validation failures when organizing your plugin directory:

- **Missing manifest** – Placing [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) anywhere other than [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) renders the plugin invisible to the marketplace crawler.

- **Orphaned markdown files** – Every `.md` file must be reachable from at least one [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md). The contribution guidelines checklist item 9 in [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md) mandates this linkage to prevent broken documentation links.

- **Deep nesting** – Exceeding three directory levels under a skill triggers build failures. Keep the hierarchy flat.

- **Script misplacement** – Runtime scripts must live inside `skills/<skill-name>/scripts/`. The Codex runtime resolves modules relative to the skill root, and it cannot locate files placed elsewhere.

## Summary

- Create each plugin under `plugins/<plugin-name>/` with a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest.
- Place static media in `assets/` and define at least one skill in `skills/<skill-name>/` containing a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry point.
- Store detailed documentation in `references/`, agent policies in `agents/`, and runtime scripts in `scripts/`.
- Maintain a maximum depth of three directory levels under any skill to comply with tooling constraints.
- Ensure every markdown file links from a parent [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) to pass validation checks.

## Frequently Asked Questions

### What happens if my plugin directory structure is missing the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file?

The marketplace crawler looks exclusively for [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) at the plugin root. If this file is missing or malformed, the plugin will not appear in the marketplace index, making it undiscoverable to users regardless of the code quality.

### Can I nest directories deeper than three levels under a skill folder?

No. The contribution guidelines at [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md) explicitly enforce a maximum depth of three levels (e.g., `skills/<skill>/<folder>/<file>.md`). Exceeding this limit causes build failures and prevents automated tooling from traversing your plugin structure. Flatten deep hierarchies by moving content into `references/` or creating separate skills.

### Where should I put API documentation and troubleshooting guides?

Move extensive documentation into the `references/` subdirectory within the relevant skill folder. This keeps the top-level [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) under 500 lines as recommended by the style guide, ensuring the marketplace displays concise entry points while maintaining detailed technical references.

### Is the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) configuration file required for all plugins?

No. The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file is optional and only necessary for plugins that require UI-specific configuration. However, you must always include the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest in `.codex-plugin/` and the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry point for every skill to satisfy the mandatory structure requirements.