How to Organize Plugin Directory Structure in the OpenAI Plugins Repository

To organize a plugin directory structure in the OpenAI Plugins repository, create a root folder under plugins/ containing a .codex-plugin/plugin.json manifest, an assets/ folder for icons, and a skills/ directory where each skill contains a mandatory 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:

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

The .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 – The manifest file that powers marketplace discovery. Example: 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 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 for UI-only configuration and 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 under 500 lines.

• agents/ – Holds YAML files defining LLM-agent policies, such as 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:

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.

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:

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 manifest must reference the skills and assets correctly:

{
  "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 file requires YAML front-matter:

---
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 anywhere other than .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. The contribution guidelines checklist item 9 in 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 manifest.
• Place static media in assets/ and define at least one skill in skills/<skill-name>/ containing a 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 to pass validation checks.

Frequently Asked Questions

What happens if my plugin directory structure is missing the .codex-plugin/plugin.json file?

The marketplace crawler looks exclusively for .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 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 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 configuration file required for all plugins?

No. The .app.json file is optional and only necessary for plugins that require UI-specific configuration. However, you must always include the plugin.json manifest in .codex-plugin/ and the SKILL.md entry point for every skill to satisfy the mandatory structure requirements.

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