PLUGIN
DOCS

The Codex Marketplace CLI installs one explicit artifact class at a time from GitHub: plugins, standalone skills, or standalone hook packages.

npx codex-marketplace add owner/repo --plugins

Available Commands

npx codex-marketplace add <owner/repo> --plugins
npx codex-marketplace add <owner/repo>/plugins/my-plugin --plugin
npx codex-marketplace add <owner/repo> --skills
npx codex-marketplace add <owner/repo>/skills/my-skill --skill
npx codex-marketplace add <owner/repo> --hooks
npx codex-marketplace add <owner/repo>/hooks/my-hook --hook
npx codex-marketplace add <owner/repo> --hook
npx codex-marketplace add <owner/repo> --plugins --project
npx codex-marketplace add <owner/repo> --plugins --global
npx codex-marketplace remove <plugin> --project
npx codex-marketplace remove <plugin> --global

If you omit --project and --global in an interactive terminal, the CLI prompts you to choose the scope before writing anything.

The typed flags are mandatory. Use singular flags only with a direct repository path such as owner/repo/plugins/name,owner/repo/skills/name, or owner/repo/hooks/name. Plural flags only crawl the matching top-level folder:plugins/, skills/, or hooks/. The installer never scans sibling folders once you choose a type.

For one plugin from a multi-plugin repository, pass the plugin's repository path and use the boolean --plugin flag. Full GitHub tree URLs still work and remain the correct way to pin a branch, tag, or commit exactly.

Plugins still provision marketplace metadata, copied plugin sources, plugin cache entries under ~/.codex/plugins/cache/, and plugin config in ~/.codex/config.toml. Standalone skills install into the Codex skill roots, and standalone hook packages install into scope-specific hooks.json plus a copied package directory for scripts and assets.

Every Codex plugin follows a standardized directory layout. The only required file is .codex-plugin/plugin.json.

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # Required manifest
├── skills/                  # Optional
│   └── my-skill/
│       └── SKILL.md
├── .app.json                # Optional: app integrations
├── .mcp.json                # Optional: MCP server config
├── hooks.json               # Optional: lifecycle hooks
└── assets/                  # Optional: icons, logos

Important: Only plugin.json belongs inside .codex-plugin/. Keep everything else at the plugin root.

The manifest is the heart of your plugin. Here's a complete example with all available fields:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "A useful plugin for Codex.",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/my-plugin",
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "workflow"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "A brief tagline (≤125 chars)",
    "longDescription": "Extended description for the marketplace.",
    "developerName": "Your Name",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://example.com",
    "defaultPrompt": ["Use My Plugin to do X"],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": ["./assets/screenshot-1.png"]
  }
}

Required Fields

• name — Unique kebab-case identifier
• version — Semantic version (e.g., "0.1.0")
• description — Brief description of the plugin

Skills are packaged instructions that teach Codex specific tasks. Each skill lives in its own directory under skills/.

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.
You should be enthusiastic and offer to assist
with their current project.

The frontmatter defines the skill's name and description. The markdown body contains the instructions Codex will follow. The installer uses --skill for one direct skills/<name> folder and --skills for the entire top-level skills/ folder.

Project installs copy skills into $REPO/.codex/skills/<name>. Global installs copy skills into ~/.agents/skills/<name>.

Standalone hook packages live under a top-level hooks/ directory and ship a required hooks.json plus any optional scripts or assets the hook needs at runtime.

hooks/
└── my-hook/
    ├── hooks.json          # Required
    ├── scripts/            # Optional
    └── assets/             # Optional

Use --hook with either a root hook repository or a direct hooks/<name> tree URL, or use --hooks for the whole top-level hooks/ folder. Project installs write to $REPO/.codex/hooks.json and $REPO/.codex/hooks/<name>. Global installs write to $CODEX_HOME/hooks.json and $CODEX_HOME/hooks/<name>. Current behavior also enables features.codex_hooks = true in the active Codex config, including project-scoped hook installs.

Nested hook package names are flattened when installed. For example, a hook under hooks/aitmpl-codex/post-tool/git-add-changesinstalls into a scoped directory name like aitmpl-codex--post-tool--git-add-changes.

Marketplace files make your plugins discoverable. Place them at:

• Repo-level: $REPO/.agents/plugins/marketplace.json
• Personal: ~/.agents/plugins/marketplace.json

{
  "name": "my-marketplace",
  "interface": {
    "displayName": "My Plugin Collection"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

For project installs, the CLI creates this file under the current directory and stores imported plugin sources under ./plugins/<plugin-name>.

For global installs, the CLI writes ~/.agents/plugins/marketplace.json and stores imported plugin sources under ~/.codex/plugins/<plugin-name>.

MCP is not installed as a standalone top-level marketplace type. MCP configuration stays bundled inside plugins through the optional .mcp.json path in .codex-plugin/plugin.json.

To list your plugin on the Codex Plugin Marketplace:

1. Create a GitHub repository with a valid .codex-plugin/plugin.json
2. Add bundled skills, bundled MCP, hooks, or app integrations as needed
3. Go to the Submit Plugin page and enter your repository URL
4. We'll validate your manifest and add it to the review queue

Signed-in users submit a GitHub repository or tree URL, the submission is queued for automated review, and anything ambiguous is routed into manual review before publication.

Once approved, users can install your plugin with a single command:

npx codex-marketplace add your-org/your-plugin --plugin --project