What Are Codex Plugins: A Package Management System for AI Workflows
I was working on an AI workflow project last week when I ran into a familiar problem. My teammate asked, “Can you share that configuration you built for code generation?” I copied three different JSON files, explained where they should go, and hoped nothing would break on their end.
That’s when I realized: we need a package manager for AI workflows. That’s exactly what Codex Plugins provide.
The Problem I Kept Running Into
Every time I built a useful AI workflow setup, sharing it was a mess:
- Manual file copying - I had to locate and share multiple configuration files
- Version drift - My teammate’s copy would diverge from mine within days
- No standard location - Where do these configs even live?
- Trial-and-error setup - “Does this skill need that MCP server? Let me check…”
The core issue: Skills, Apps, and MCP Servers live in separate files with separate concerns. Sharing them together requires manual coordination.
Project A Project B├── .mcp.json ──────────────────► ┌── .mcp.json (outdated)├── .app.json ──────────────────► ├── .app.json (missing fields)└── skills/ └── skills/ ├── code-gen.md ───────────► └── code-gen.md (old version) └── testing.mdI’d share my setup, but without a packaging system, the recipient would miss something, get a different version, or put files in the wrong place.
What Codex Plugins Actually Are
Codex Plugins are a package management system for the Codex ecosystem. They bundle three core components into a single installable entity:
| Component | What It Does |
|---|---|
| Skills | Workflow descriptions - prompts and instructions for AI |
| Apps | Application connectors - links to external services |
| MCP Servers | Remote tools or shared context - extended capabilities |
Instead of sharing three separate configurations, you share one plugin. It’s like the difference between emailing someone a zip file versus publishing an npm package.
How Plugins Work: A Concrete Example
I’ll walk through how I converted my team’s workflow into a plugin.
Before: Scattered Configurations
My project had these files:
{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@anthropic/github-mcp-server"] }, "slack": { "command": "npx", "args": ["-y", "@anthropic/slack-mcp-server"] } }}{ "apps": { "jira": { "type": "jira", "baseUrl": "https://company.atlassian.net" } }}# Code Review Skill
Review code changes following team standards:1. Check for test coverage2. Verify naming conventions3. Flag security concerns4. Suggest improvementsSharing this meant explaining three files, their locations, and how they relate.
After: A Single Plugin
I created a plugin manifest:
{ "name": "team-workflow-plugin", "version": "1.0.0", "description": "Shared AI workflow for team productivity", "skills": "./skills", "mcpServers": "./.mcp.json", "apps": "./.app.json", "interface": { "displayName": "Team Workflow Plugin", "category": "productivity", "capabilities": ["code-review", "testing"], "brandColor": "#4F46E5" }}Now my teammates install it with a single command (conceptually):
codex plugin install team-workflow-pluginAll three components land in the right places, versioned and trackable.
The Key Distinction: Local Skills vs Plugins
I initially confused local Skills with Plugins. Here’s the difference I learned:
┌─────────────────────────────────────────────────────────────────┐│ WHEN TO USE WHAT │├─────────────────────────────────────────────────────────────────┤│ ││ LOCAL SKILLS PLUGINS ││ ──────────── ──────── ││ ✓ Experimenting ✓ Production-ready ││ ✓ Project-specific ✓ Cross-project reuse ││ ✓ Quick iterations ✓ Team sharing ││ ✓ No versioning needed ✓ Version management ││ ✓ Living in your skills/ ✓ Install from marketplace ││ ││ Example: Example: ││ "Let me test this prompt..." "This workflow works, let me ││ package it for the team." ││ │└─────────────────────────────────────────────────────────────────┘Local Skills are for you - experimental, rapid iteration, no ceremony.
Plugins are for teams - stable, versioned, discoverable.
Why This Matters
Without a package management system, teams face:
- Configuration drift - Everyone has slightly different setups
- Re-invention - Each project builds similar workflows from scratch
- Onboarding friction - New team members need manual setup guidance
- No versioning - “Which version of that skill are you using?”
Plugins solve all four by providing a single source of truth with version control.
When Should You Create a Plugin?
I created my first plugin after answering “yes” to these questions:
- Does this workflow work reliably?
- Would another project benefit from it?
- Am I tired of explaining how to set it up?
- Does it combine Skills, Apps, or MCP Servers?
If you’re nodding along, it’s time to package your workflow.
Common Mistakes I Made
Mistake 1: Packaging Experimental Skills Too Early
I tried to create a plugin after my first successful workflow test. Bad idea. The workflow changed three times that week. Now I follow a rule: use it locally for two weeks before packaging.
Mistake 2: Forgetting Dependencies
My plugin referenced an MCP server but didn’t document its requirements. Teammates got cryptic errors. The fix: document all prerequisites in the plugin description.
Mistake 3: No Version Strategy
I published version 1.0.0, then made breaking changes without updating the version. SemVer exists for a reason. Now I follow:
MAJOR.MINOR.PATCH │ │ │ │ │ └── Bug fixes, no API changes │ └──────── New features, backward compatible └────────────── Breaking changesThe Plugin Ecosystem View
Here’s how Plugins fit into the broader Codex picture:
┌─────────────────────────────────────────────────────────────────┐│ CODEX ECOSYSTEM │├─────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ Skills │ │ Apps │ │ MCP Servers │ ││ │ │ │ │ │ │ ││ │ Prompts & │ │ External │ │ Remote │ ││ │ Instructions│ │ Connectors │ │ Tools │ ││ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ ││ │ │ │ ││ └───────────────────┼───────────────────┘ ││ │ ││ ┌─────────▼─────────┐ ││ │ PLUGINS │ ││ │ │ ││ │ Package Manager │ ││ │ for All Three │ ││ └─────────┬─────────┘ ││ │ ││ ┌─────────▼─────────┐ ││ │ Marketplace │ ││ │ │ ││ │ Discover & Share │ ││ └───────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘Plugins don’t replace Skills, Apps, or MCP Servers - they bundle them for distribution.
What I Wish I Knew Earlier
- Start local, then package - Don’t jump straight to plugin creation
- Test with teammates before publishing - Fresh eyes catch missing docs
- Use descriptive interface metadata - Good
displayNameandcapabilitieshelp discovery - Version from day one - Even 0.1.0 is better than no version
Summary
Codex Plugins solve the real problem I faced: sharing AI workflow configurations without the copy-paste chaos. They bundle Skills, Apps, and MCP Servers into versioned, installable packages.
The key insight: local Skills are for experimenting, Plugins are for sharing. Know when to use which, and you’ll avoid the mistakes I made.
If you’re building AI workflows that others could use, start thinking about plugins. Your future teammates will thank you.
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:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments