How to Build a Plugin for OpenAI Codex

Build a Codex plugin with a SKILL.md capability: create the plugin package, trigger its Skill, and measure performance across versions with Telvine.

This guide shows how to build a plugin for OpenAI Codex. Codex uses plugins as the installable distribution unit for reusable Skills, apps, MCP config, hooks, and assets. A plugin can package a SKILL.md capability alongside integrations and other resources, so users install one product while Codex loads the right capability for the task.

Plugins, Skills, and AGENTS.md

Codex reads two kinds of customization:

AGENTS.md — always-on repository instructions (setup commands, test commands, coding standards). Use it for rules that apply to every task.
Skills — reusable, agent-triggered capabilities defined in a SKILL.md, with optional scripts and references.
Plugins — installable packages that distribute one or more Skills and may also bundle app integrations or MCP configuration.

If a capability is "do this specific job when asked," write a Skill. If you want others to install and manage it as a product, ship it in a plugin.

Step 1 — Write the SKILL.md

---
name: migration-writer
description: >
  Use this skill when the user asks to "write a database migration",
  "add a migration", or "change the schema". Generates a migration
  and its rollback from a described schema change.
---
 
# Migration writer
## Steps
1. Read the current schema and the requested change.
2. Generate the migration and a matching rollback.
3. Never run the migration — output it for review.

The description is what makes Codex pick the Skill, so write it in the third person with the phrases a developer would actually type.

Step 2 — Package it as a plugin

Create a plugin folder with a .codex-plugin/plugin.json manifest and add the Skill under skills/:

my-plugin/
├── .codex-plugin/plugin.json
└── skills/
    └── migration-writer/
        └── SKILL.md

Local repo Skills are useful while authoring. A plugin is the distribution unit when the capability is ready for other people to install.

Step 3 — Trigger and refine

Describe the task the way you normally would in Codex. If the Skill doesn't trigger, tighten the description — that's where almost all iteration happens. Add scripts/ for deterministic steps (parsing, codegen, validation) so the agent doesn't improvise logic that should be exact.

Step 4 — Measure it with Telvine

A plugin is software, and each Skill is an observable capability inside it. Telvine tracks invocations, errors, and latency for your plugin's Skills, compares versions with statistical significance, and pipes events to your warehouse — using a closed event envelope that never carries prompts or code. Wrap the SKILL.md inside your plugin and you will know whether the latest shipped capability improved.

Keep the capability portable

The SKILL.md you wrote inside a Codex plugin can also run in harnesses that support agent Skills. Distribution packages vary by harness; the capability itself stays portable and can be measured in one place.

Frequently asked questions

When should I use a Skill instead of AGENTS.md? Use AGENTS.md for always-on rules; use a Skill for a reusable workflow with richer instructions, scripts, or references.

Why do I need both a plugin and a Skill? A Skill defines a task-specific capability; a plugin is how you package that capability for installation and distribution in Codex.