# 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. ## 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 | Characteristic | Standalone Skill | Modular Plugin | | :--- | :--- | :--- | | **Primary Purpose** | Defines rules and procedures for an individual task | A self-contained package extending the agent's runtime environment | | **Package Contents** | Markdown file `SKILL.md` + optional reference notes | Collection of Skills, MCP servers, lifecycle hooks, and configs | | **External Integrations** | Cannot connect to third-party APIs natively | Integrates external services via Model Context Protocol (MCP) | | **Distribution** | Manual folder copying into the workspace directory | One-click install via GUI or single CLI command from Marketplaces | | **Updates** | Manual file replacement by developer | Automated 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 :::tabs @tab List Installed ```bash # Display all plugins currently installed in your local environment codex plugin list ``` @tab List Available ```bash # Query all plugins available across connected marketplaces codex plugin list --available # Output full metadata in machine-readable JSON format codex plugin list --available --json ``` @tab Install Plugin ```bash # Install a plugin by its package name codex plugin add github-toolkit # Install explicitly from a designated marketplace codex plugin add dev-suite@company-internal ``` @tab Uninstall Plugin ```bash # Completely remove an installed plugin from your environment codex plugin remove github-toolkit # Remove a plugin tied to a specific marketplace source codex plugin remove dev-suite@company-internal ``` ::: 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: :::tabs @tab GitHub Shorthand ```bash # Shorthand notation for public or accessible GitHub repositories (owner/repo) codex plugin marketplace add orlov-ai/community-plugins ``` @tab HTTPS Git URL ```bash # Standard HTTPS URL (compatible with public or authenticated GitLab/Bitbucket) codex plugin marketplace add https://github.com/company/internal-codex-plugins.git ``` @tab SSH Git URL ```bash # Private SSH connection for enterprise internal code hosts codex plugin marketplace add git@github.com:enterprise/secure-plugins.git ``` @tab Local Directory ```bash # Mount a local filesystem directory for plugin authoring and testing codex plugin marketplace add ./my-local-marketplace ``` ::: ### 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: | Action | Command / Interface | Filesystem Impact | Session Consequence | | :--- | :--- | :--- | :--- | | **Disable Plugin** | Toggle switch in `/plugins` | Retains files on disk; configuration preserved | Skills and MCP tools become inactive in new sessions | | **Uninstall Plugin** | `codex plugin remove ` | Deletes all plugin files from local cache | Complete removal; reinstallation required for future use | | **Remove Marketplace** | `codex plugin marketplace remove ` | Unlinks catalog only; installed plugins remain | Cannot 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 # Install a plugin codex plugin add # Install from a specific marketplace codex plugin remove # Uninstall a plugin # ─── Marketplace Operations ─────────────────────────────────────── codex plugin marketplace list # List connected marketplaces codex plugin marketplace add # Add marketplace (GitHub / URL / Local path) codex plugin marketplace upgrade # Refresh a specific marketplace index codex plugin marketplace upgrade # Refresh all connected marketplaces codex plugin marketplace remove # 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.