Skip to main content
All guides
Guide contents

Guide contents

Time to study: 15 min
#ai_agents#codex#plugins#skills#mcp#marketplace
Intermediate15 min

Codex Plugins for Beginners: The Complete Guide to the New Skill Ecosystem

A comprehensive guide to the Codex plugin ecosystem: understanding Skills vs. Plugins, connecting Marketplaces, GUI and CLI management, MCP server authorization, and packaging custom plugins.

Published:

1. Ecosystem Evolution: From Basic Skills to Modular Plugins

In the early stages of autonomous AI development environments, the primary tool for tailoring agent behavior was Skills—isolated folders containing Markdown instruction files (SKILL.md) that taught the model how to perform specific workflows: executing team-standard code reviews, optimizing database queries, or drafting technical documentation.

While Skills remain the fundamental atom of agent knowledge, manual file copying across repositories, the absence of dependency versioning, and the inability to bundle executable tools alongside instructions highlighted the need for a modern, modular distribution architecture: Codex Plugins and Marketplaces.

mermaid
flowchart TD subgraph Distribution ["Distribution Layer"] M["Marketplace (Git repo or local folder)"] end subgraph Packaging ["Packaging Layer: Plugin"] P["Codex Plugin"] P --> S["Skills (Instructions and domain knowledge)"] P --> T["MCP Tools (External APIs: GitHub, Slack, Figma)"] P --> H["Hooks (Automated lifecycle triggers)"] P --> C["Config (Manifest plugin.json)"] end subgraph Execution ["Execution Layer"] Session["New Active Codex Session"] end M -->|codex plugin add| P P -->|Initialize extensions| Session

Architectural Comparison: Skill vs. Plugin

CharacteristicStandalone SkillModular Plugin
Primary PurposeDefines rules and procedures for an individual taskA self-contained package extending the agent's runtime environment
Package ContentsMarkdown file SKILL.md + optional reference notesCollection of Skills, MCP servers, lifecycle hooks, and configs
External IntegrationsCannot connect to third-party APIs nativelyIntegrates external services via Model Context Protocol (MCP)
DistributionManual folder copying into the workspace directoryOne-click install via GUI or single CLI command from Marketplaces
UpdatesManual file replacement by developerAutomated updates via CLI or extension catalog
Note

The most accurate analogy is software packaging: Skills are individual library functions, whereas Plugins are complete packages (like npm modules). If you only need a self-contained prompt instruction, a Skill is sufficient. If you want to grant the agent live API access to GitHub, Slack, or Figma alongside automated execution recipes, choose a Plugin.

2. Anatomy of a Plugin: Skills, MCP Servers, Configurations, and Hooks

A Codex Plugin is not merely an extended system prompt. It is a well-structured directory or archive featuring a declarative manifest and executable assets.

text
my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Required plugin manifest ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Embedded first skill │ └── perf-audit/ │ └── SKILL.md # Embedded second skill ├── mcp/ │ └── server-config.json # MCP server configuration └── README.md # Developer documentation

Core Components of a Modern Plugin

  1. Manifest (.codex-plugin/plugin.json): The primary configuration file defining the plugin's unique identifier, semantic version, author metadata, dependencies, and entrypoints.
  2. Skill Bundles (skills/): One or more directories with SKILL.md files that instruct Codex on specialized engineering practices.
  3. MCP Servers (Model Context Protocol): Executable servers or adapters that equip the agent with live tools—such as inspecting GitHub pull requests, creating Linear tickets, or inspecting Figma design tokens.
  4. Lifecycle Hooks: Scripts or terminal commands triggered automatically during specific lifecycle stages (e.g., executing a linter prior to git commit actions).
json
{ "name": "developer-toolkit", "version": "1.2.0", "description": "Comprehensive toolkit for code auditing and GitHub automation", "author": "Engineering Team", "skills": [ "./skills/code-review", "./skills/perf-audit" ], "mcpServers": { "github-connector": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }
Important

Unlike plain text prompts, plugins fundamentally expand the agent's executable tooling capabilities. Without an MCP-enabled plugin, the agent merely reasons about interacting with GitHub; with the plugin installed, it gains native tools to call the GitHub API directly.

3. What Are Marketplaces: Extension Catalogs and Distribution Sources

To discover, verify, and distribute plugins efficiently, Codex introduces Marketplaces.

A Marketplace is a central catalog or registry containing a list of available plugins, metadata, and download endpoints. Instead of scouring unverified websites for archives, developers register trusted marketplaces and install extensions using clean identifier slugs.

mermaid
flowchart LR subgraph Sources ["Marketplace Sources"] Official["Official OpenAI Registry"] Community["Public GitHub Repositories"] Private["Internal Corporate Registries"] Local["Local Development Folders"] end subgraph Client ["Codex Client Environment"] Reg["Marketplace Manager"] Reg --> P1["Plugin: GitHub Sync"] Reg --> P2["Plugin: PostgreSQL Inspector"] Reg --> P3["Plugin: Team Styleguide"] end Official --> Reg Community --> Reg Private --> Reg Local --> Reg

Supported Marketplace Categories

  • Official Public Registry: Built-in default registry available to all Codex users, containing verified extensions for mainstream services (Figma, Notion, Google Workspace, GitHub).
  • Community Git Repositories: Any public or private repository on GitHub or GitLab adhering to the marketplace layout specification.
  • Internal Corporate Registries: Private organizational catalogs housing proprietary plugins that interact with internal microservices, company VPNs, and security gateways.
  • Local Development Directories: Plain local filesystem paths utilized for scaffolding, testing, and debugging plugins before deployment.

4. Graphical Interface Management: The /plugins Command

For daily development tasks, engineers do not need to memorize extensive terminal syntax—Codex provides an interactive graphical plugin browser directly in the session.

Accessing the Interactive GUI

To launch the visual management interface, type the following slash command in your active Codex chat input:

bash
/plugins

The interactive manager allows you to:

  • Inspect Installed Plugins: Review all active extensions and their real-time execution status.
  • Search New Packages: Filter plugins by name, tags, or domain categories (Development, DevOps, Analytics, Design).
  • Switch Between Marketplaces: Select specific connected catalogs to isolate available extensions.
  • Toggle State: Enable or temporarily disable installed plugins with a single click without removing their files.
Warning

New Session Rule: When installing a new plugin or toggling an existing one, its skills and MCP tools become active only in newly created sessions. Running sessions preserve their initial execution state; always open a fresh dialog after adjusting plugin configurations.

5. Managing Plugins via CLI: List, Install, and Remove

For terminal-first developers and automation pipelines (CI/CD runners, containerized environments), Codex provides comprehensive command-line tooling under the codex plugin namespace.

Essential Plugin Commands

The codex plugin list command provides an overview of each plugin's name, version, origin marketplace, and current enablement state.

6. Managing Marketplaces: Adding, Updating, and Removing Sources

To expand your catalog of available extensions, connect external sources using the codex plugin marketplace subcommands.

Viewing Connected Catalogs

bash
codex plugin marketplace list

This command reports the registered alias, source protocol (git or local), and target URI for every connected registry.

Adding New Marketplace Sources

Codex accommodates various transport protocols depending on your infrastructure:

Updating and Removing Marketplaces

bash
# Refresh metadata for a specific marketplace codex plugin marketplace upgrade community-plugins # Refresh all connected Git-based marketplaces concurrently codex plugin marketplace upgrade # Unregister a marketplace from your environment codex plugin marketplace remove community-plugins
Tip

If a teammate recently published a new plugin version that is not yet visible in your search, run codex plugin marketplace upgrade to synchronize your local registry index.

7. Plugins with MCP Servers: Authorization, Permissions, and Security

When a plugin embeds an MCP server, it gains the capability to communicate with external web services, remote databases, and cloud APIs. This transforms Codex from a code-generating assistant into an active automation agent.

mermaid
sequenceDiagram autonumber actor Dev as Engineer participant Codex as Codex Session participant Plugin as Plugin (MCP Adapter) participant Cloud as External API (GitHub) Dev->>Codex: "Create an issue with audit findings" Codex->>Plugin: Invoke create_issue() tool alt Authorization Required Plugin-->>Dev: Prompt for OAuth approval or API key Dev->>Plugin: Confirm credentials end Plugin->>Cloud: POST /repos/:owner/:repo/issues Cloud-->>Plugin: HTTP 201 Created (Issue #42) Plugin-->>Codex: Result with issue hyperlink Codex-->>Dev: "Issue #42 created successfully!"

External Service Authorization Paradigms

  1. OAuth Authentication Flow: Cloud services (Google Drive, Slack, GitHub) open a browser window during first tool invocation, prompting for user account authorization.
  2. Environment Variables for Secrets: Database adapters and internal APIs (PostgreSQL, Supabase) source credentials from local .env configurations or Codex settings.
  3. Granular Human-in-the-Loop Permissions: Codex solicits explicit confirmation prior to executing state-altering actions (e.g., deleting records, sending emails, merging PRs).
Warning

MCP Security Hygiene: Never install third-party plugins from unvetted marketplaces if they bundle MCP servers. Malicious MCP servers could inspect local disk contents or exfiltrate private environment secrets. Always review source code before installation.

8. Lifecycle Management: Disabling, Uninstalling, or Removing Marketplaces

Developers frequently confuse the three tiers of plugin lifecycle deactivation:

ActionCommand / InterfaceFilesystem ImpactSession Consequence
Disable PluginToggle switch in /pluginsRetains files on disk; configuration preservedSkills and MCP tools become inactive in new sessions
Uninstall Plugincodex plugin remove <name>Deletes all plugin files from local cacheComplete removal; reinstallation required for future use
Remove Marketplacecodex plugin marketplace remove <name>Unlinks catalog only; installed plugins remainCannot download new packages or updates from this source

Decision Guide

  • If a plugin conflicts with existing tools or you want to temporarily suspend heavy MCP servers, choose Disable.
  • If a project is complete and you will no longer use the toolset, choose Uninstall (Remove).
  • If a developer registry is decommissioned or moved, choose Remove Marketplace.

9. Authoring a Custom Plugin: Manifest, Skill Packaging, and Local Testing

Packaging your team's best practices into a private plugin is the most effective strategy to enforce consistent architectural quality across engineering teams.

Step-by-Step Scaffolding Guide

Step 1. Initialize Plugin Directory

Create an isolated workspace structure:

bash
mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review

Step 2. Create the plugin.json Manifest

Create .codex-plugin/plugin.json:

json
{ "name": "team-architecture-plugin", "version": "1.0.0", "description": "Proprietary service design guidelines and clean architecture auditor", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] }

Step 3. Implement Domain Rules in SKILL.md

Create my-team-plugin/skills/architecture-review/SKILL.md:

markdown
--- name: architecture-review description: Verify module compliance with Domain-Driven Design (DDD) principles --- When analyzing new architectural modules, ensure the following rules: 1. Business logic must never import the ORM or raw database drivers directly. 2. External integrations must be modeled as ports (interfaces) in the core domain layer. 3. Every state mutation must emit an audited domain event.

Step 4. Create a Local Marketplace and Install

To test your plugin locally without pushing to GitHub, register the parent directory as a local marketplace:

bash
# Register local directory as a marketplace source codex plugin marketplace add ./local-market # Install the newly packaged plugin codex plugin add team-architecture-plugin # Verify installation status codex plugin list

Start a new Codex session and test the new skill against a realistic architectural review prompt.

10. Command Cheat Sheet and Pre-Installation Security Checklist

Keep this reference guide accessible for rapid command lookups and secure workstation hygiene.

Complete CLI Command Reference

bash
# ─── Plugin Operations ─────────────────────────────────────────── codex plugin list # List installed plugins codex plugin list --available # List available plugins from registries codex plugin add <plugin-name> # Install a plugin codex plugin add <plugin@marketplace> # Install from a specific marketplace codex plugin remove <plugin-name> # Uninstall a plugin # ─── Marketplace Operations ─────────────────────────────────────── codex plugin marketplace list # List connected marketplaces codex plugin marketplace add <source> # Add marketplace (GitHub / URL / Local path) codex plugin marketplace upgrade <name> # Refresh a specific marketplace index codex plugin marketplace upgrade # Refresh all connected marketplaces codex plugin marketplace remove <name> # Unlink a marketplace # ─── Visual Interface ───────────────────────────────────────────── /plugins # Launch interactive visual browser

Pre-Installation Security Checklist

  • Verified Origin: The marketplace repository belongs to an official company or established open-source maintainer.
  • Manifest Audit: Inspect plugin.json for suspicious executable commands or unvetted binary dependencies.
  • Network Endpoint Verification: Any bundled MCP server connects strictly to official API endpoints.
  • Namespace Safety: Embedded skills do not silently override critical system-level instructions.
  • Isolated Session Verification: Test new plugins in a dedicated sandbox project before deploying into production codebases.
This guide is completely free. If it saved you an evening, you can support the project's growth.
Support the author