How to Structure Your First Codex Plugin Directory and Manifest

Mar 27, 2026

I tried creating my first Codex Plugin last week, and I got an error: “Plugin manifest not found.” I spent hours checking my file paths, trying different directory names, and wondering why my plugin wouldn’t load.

The problem? I didn’t understand the required directory structure. Codex Plugins need a specific layout, and the manifest file must be in the right place. Let me walk you through what I learned.

The Problem: No Standard Structure

When I started, I thought I could organize my plugin however I wanted. I created a folder called my-plugin and put a plugin.json file right at the root:

my-plugin/
├── plugin.json        # WRONG: Not in .codex-plugin directory
├── skills/
│   └── my-skill.md
└── README.md

Codex couldn’t find my manifest. I kept getting the same error over and over. The issue was that Codex expects the manifest in a specific location: inside a .codex-plugin directory.

The Solution: Follow the Standard Structure

Here’s the correct structure that Codex expects:

my-plugin/
├── .codex-plugin/
│   └── plugin.json    # REQUIRED: Must be here
├── skills/            # OPTIONAL: Workflow definitions
├── .app.json          # OPTIONAL: App integrations
├── .mcp.json          # OPTIONAL: MCP server configs
└── assets/            # OPTIONAL: Icons, screenshots

The key insight: Every Codex Plugin must have a .codex-plugin/plugin.json file. This is non-negotiable. Everything else is optional.

Understanding Each Component

The Required Manifest (`.codex-plugin/plugin.json`)

This file defines your plugin’s identity and tells Codex where to find everything. Here’s a minimal example:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "A simple example plugin"
}

The name field must use kebab-case (lowercase letters, numbers, and hyphens only). No spaces, no camelCase, no underscores.

Optional Skills Directory (`skills/`)

If your plugin includes workflow descriptions (called “skills”), put them in a skills/ directory:

skills/
├── code-review/
│   └── SKILL.md
├── deploy/
│   └── SKILL.md
└── test/
    └── SKILL.md

Each skill gets its own folder with a SKILL.md file inside. The agent discovers these progressively as users interact with your plugin.

Optional Configuration Files

.app.json - For connecting external services:

{
  "apps": {
    "github": {
      "type": "oauth",
      "clientId": "your-client-id"
    }
  }
}

.mcp.json - For MCP server configurations:

{
  "mcpServers": {
    "fetch": {
      "command": "node",
      "args": ["./mcp-servers/fetch.js"]
    }
  }
}

Optional Assets Directory (`assets/`)

Visual assets for marketplace display:

assets/
├── icon.png          # Plugin icon (512x512 recommended)
└── screenshot.png    # Marketplace screenshot

Common Mistakes I Made

Mistake 1: Using Absolute Paths

I initially used absolute paths in my manifest:

{
  "skills": "/Users/me/my-plugin/skills"  // WRONG: Absolute path
}

All paths in the manifest must be relative and start with ./:

{
  "skills": "./skills"  // CORRECT: Relative path
}

Mistake 2: Forgetting the `.codex-plugin` Prefix

I tried putting the manifest at the root level, skipping the .codex-plugin directory entirely. This doesn’t work. Codex specifically looks for .codex-plugin/plugin.json.

Mistake 3: Wrong Naming Convention

I used myFirstPlugin (camelCase) for the name field. This caused validation errors. Use kebab-case: my-first-plugin.

A Complete Working Example

Here’s a complete plugin structure with all components:

{
  "name": "team-productivity-suite",
  "version": "2.1.0",
  "description": "Comprehensive productivity workflows for development teams",
  "skills": "./skills",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team Productivity Suite",
    "category": "productivity",
    "capabilities": [
      "code-generation",
      "testing",
      "documentation",
      "deployment"
    ],
    "brandColor": "#10B981"
  }
}

team-productivity-suite/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── deploy/
│   │   └── SKILL.md
│   └── test/
│       └── SKILL.md
├── .app.json
├── .mcp.json
└── assets/
    ├── icon.png
    └── screenshot.png

Why This Matters

A consistent structure enables:

Marketplace Integration: Codex can index, display, and install your plugin reliably
Team Sharing: Other developers can understand your plugin layout immediately
Portability: Your plugin works across different Codex installations
Maintainability: Clear separation of concerns (skills, configs, assets)

Next Steps

After setting up your directory structure, you’ll want to:

Test your plugin locally using codex plugin install ./my-plugin
Add more skills to your skills/ directory
Configure MCP servers in .mcp.json for extended capabilities
Publish to the Codex Marketplace when ready

The structure isn’t complicated once you understand the requirements. Start with the required manifest, add optional components as needed, and always use relative paths.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Codex Plugin Documentation
👨‍💻 MCP Server Configuration Guide

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!