plugins/build.md +359 −0 added
1# Build plugins
2
3This page is for plugin authors. If you want to browse, install, and use
4plugins in Codex, see [Plugins](https://developers.openai.com/codex/plugins). If you are still iterating on
5one repo or one personal workflow, start with a local skill. Build a plugin
6when you want to share that workflow across teams, bundle app integrations or
7MCP config, or publish a stable package.
8
9## Create a plugin with `$plugin-creator`
10
11For the fastest setup, use the built-in `$plugin-creator` skill.
12
13
14
15It scaffolds the required `.codex-plugin/plugin.json` manifest and can also
16generate a local marketplace entry for testing. If you already have a plugin
17folder, you can still use `$plugin-creator` to wire it into a local
18marketplace.
19
20
21
22### Build your own curated plugin list
23
24A marketplace is a JSON catalog of plugins. `$plugin-creator` can generate one
25for a single plugin, and you can keep adding entries to that same marketplace
26to build your own curated list for a repo, team, or personal workflow.
27
28In Codex, each marketplace appears as a selectable source in the plugin
29directory. Use `$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped
30list or `~/.agents/plugins/marketplace.json` for a personal list. Add one
31entry per plugin under `plugins[]`, point each `source.path` at the plugin
32folder with a `./`-prefixed path relative to the marketplace root, and set
33`interface.displayName` to the label you want Codex to show in the marketplace
34picker. Then restart Codex. After that, open the plugin directory, choose your
35marketplace, and browse or install the plugins in that curated list.
36
37You don't need a separate marketplace per plugin. One marketplace can expose a
38single plugin while you are testing, then grow into a larger curated catalog as
39you add more plugins.
40
41
42
43### Create a plugin manually
44
45Start with a minimal plugin that packages one skill.
46
471. Create a plugin folder with a manifest at `.codex-plugin/plugin.json`.
48
49```bash
50mkdir -p my-first-plugin/.codex-plugin
51```
52
53`my-first-plugin/.codex-plugin/plugin.json`
54
55```json
56{
57 "name": "my-first-plugin",
58 "version": "1.0.0",
59 "description": "Reusable greeting workflow",
60 "skills": "./skills/"
61}
62```
63
64Use a stable plugin `name` in kebab-case. Codex uses it as the plugin
65identifier and component namespace.
66
672. Add a skill under `skills/<skill-name>/SKILL.md`.
68
69```bash
70mkdir -p my-first-plugin/skills/hello
71```
72
73`my-first-plugin/skills/hello/SKILL.md`
74
75```md
76---
77name: hello
78description: Greet the user with a friendly message.
79---
80
81Greet the user warmly and ask how you can help.
82```
83
843. Add the plugin to a marketplace. Use `$plugin-creator` to generate one, or
85 follow [Build your own curated plugin list](#build-your-own-curated-plugin-list)
86 to wire the plugin into Codex manually.
87
88From there, you can add MCP config, app integrations, or marketplace metadata
89as needed.
90
91### Install a local plugin manually
92
93Use a repo marketplace or a personal marketplace, depending on who should be
94able to access the plugin or curated list.
95
96 Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`
97 and store your plugins under `$REPO_ROOT/plugins/`.
98
99 **Repo marketplace example**
100
101 Step 1: Copy the plugin folder into `$REPO_ROOT/plugins/my-plugin`.
102
103```bash
104mkdir -p ./plugins
105cp -R /absolute/path/to/my-plugin ./plugins/my-plugin
106```
107
108 Step 2: Add or update `$REPO_ROOT/.agents/plugins/marketplace.json` so
109 that `source.path` points to that plugin directory with a `./`-prefixed
110 relative path:
111
112```json
113{
114 "name": "local-repo",
115 "plugins": [
116 {
117 "name": "my-plugin",
118 "source": {
119 "source": "local",
120 "path": "./plugins/my-plugin"
121 },
122 "policy": {
123 "installation": "AVAILABLE",
124 "authentication": "ON_INSTALL"
125 },
126 "category": "Productivity"
127 }
128 ]
129}
130```
131
132 Step 3: Restart Codex and verify that the plugin appears.
133
134 Add a marketplace file at `~/.agents/plugins/marketplace.json` and store
135 your plugins under `~/.codex/plugins/`.
136
137 **Personal marketplace example**
138
139 Step 1: Copy the plugin folder into `~/.codex/plugins/my-plugin`.
140
141```bash
142mkdir -p ~/.codex/plugins
143cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin
144```
145
146 Step 2: Add or update `~/.agents/plugins/marketplace.json` so that the
147 plugin entry's `source.path` points to that directory.
148
149 Step 3: Restart Codex and verify that the plugin appears.
150
151The marketplace file points to the plugin location, so those directories are
152examples rather than fixed requirements. Codex resolves `source.path` relative
153to the marketplace root, not relative to the `.agents/plugins/` folder. See
154[Marketplace metadata](#marketplace-metadata) for the file format.
155
156After you change the plugin, update the plugin directory that your marketplace
157entry points to and restart Codex so the local install picks up the new files.
158
159### Marketplace metadata
160
161If you maintain a repo marketplace, define it in
162`$REPO_ROOT/.agents/plugins/marketplace.json`. For a personal marketplace, use
163`~/.agents/plugins/marketplace.json`. A marketplace file controls plugin
164ordering and install policies in Codex-facing catalogs. It can represent one
165plugin while you are testing or a curated list of plugins that you want Codex
166to show together under one marketplace name. Before you add a plugin to a
167marketplace, make sure its `version`, publisher metadata, and install-surface
168copy are ready for other developers to see.
169
170```json
171{
172 "name": "local-example-plugins",
173 "interface": {
174 "displayName": "Local Example Plugins"
175 },
176 "plugins": [
177 {
178 "name": "my-plugin",
179 "source": {
180 "source": "local",
181 "path": "./plugins/my-plugin"
182 },
183 "policy": {
184 "installation": "AVAILABLE",
185 "authentication": "ON_INSTALL"
186 },
187 "category": "Productivity"
188 },
189 {
190 "name": "research-helper",
191 "source": {
192 "source": "local",
193 "path": "./plugins/research-helper"
194 },
195 "policy": {
196 "installation": "AVAILABLE",
197 "authentication": "ON_INSTALL"
198 },
199 "category": "Productivity"
200 }
201 ]
202}
203```
204
205- Use top-level `name` to identify the marketplace.
206- Use `interface.displayName` for the marketplace title shown in Codex.
207- Add one object per plugin under `plugins` to build a curated list that Codex
208 shows under that marketplace title.
209- Point each plugin entry's `source.path` at the plugin directory you want
210 Codex to load. For repo installs, that often lives under `./plugins/`. For
211 personal installs, a common pattern is `./.codex/plugins/<plugin-name>`.
212- Keep `source.path` relative to the marketplace root, start it with `./`, and
213 keep it inside that root.
214- Always include `policy.installation`, `policy.authentication`, and
215 `category` on each plugin entry.
216- Use `policy.installation` values such as `AVAILABLE`,
217 `INSTALLED_BY_DEFAULT`, or `NOT_AVAILABLE`.
218- Use `policy.authentication` to decide whether auth happens on install or
219 first use.
220
221The marketplace controls where Codex loads the plugin from. `source.path` can
222point somewhere else if your plugin lives outside those example directories. A
223marketplace file can live in the repo where you are developing the plugin or in
224a separate marketplace repo, and one marketplace file can point to one plugin
225or many.
226
227### How Codex uses marketplaces
228
229A plugin marketplace is a JSON catalog of plugins that Codex can read and
230install.
231
232Codex can read marketplace files from:
233
234- the curated marketplace that powers the official Plugin Directory
235- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`
236- a personal marketplace at `~/.agents/plugins/marketplace.json`
237
238You can install any plugin exposed through a marketplace. Codex installs
239plugins into
240`~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/`. For local
241plugins, `$VERSION` is `local`, and Codex loads the installed copy from that
242cache path rather than directly from the marketplace entry.
243
244You can enable or disable each plugin individually. Codex stores each plugin's
245on or off state in `~/.codex/config.toml`.
246
247## Package and distribute plugins
248
249### Plugin structure
250
251Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include
252a `skills/` directory, an `.app.json` file that points at one or more apps or
253connectors, and assets used to present the plugin across supported surfaces.
254
255- my-plugin/
256
257 - .codex-plugin/
258
259 - plugin.json Required: plugin manifest
260 - skills/
261
262 - my-skill/
263
264 - SKILL.md Optional: skill instructions
265 - .app.json Optional: app or connector mappings
266 - .mcp.json Optional: MCP server configuration
267 - assets/ Optional: icons, logos, screenshots
268
269Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,
270`.mcp.json`, and `.app.json` at the plugin root.
271
272Published plugins typically use a richer manifest than the minimal example that
273appears in quick-start scaffolds. The manifest has three jobs:
274
275- Identify the plugin.
276- Point to bundled components such as skills, apps, or MCP servers.
277- Provide install-surface metadata such as descriptions, icons, and legal
278 links.
279
280Here's a complete manifest example:
281
282```json
283{
284 "name": "my-plugin",
285 "version": "0.1.0",
286 "description": "Bundle reusable skills and app integrations.",
287 "author": {
288 "name": "Your team",
289 "email": "team@example.com",
290 "url": "https://example.com"
291 },
292 "homepage": "https://example.com/plugins/my-plugin",
293 "repository": "https://github.com/example/my-plugin",
294 "license": "MIT",
295 "keywords": ["research", "crm"],
296 "skills": "./skills/",
297 "mcpServers": "./.mcp.json",
298 "apps": "./.app.json",
299 "interface": {
300 "displayName": "My Plugin",
301 "shortDescription": "Reusable skills and apps",
302 "longDescription": "Distribute skills and app integrations together.",
303 "developerName": "Your team",
304 "category": "Productivity",
305 "capabilities": ["Read", "Write"],
306 "websiteURL": "https://example.com",
307 "privacyPolicyURL": "https://example.com/privacy",
308 "termsOfServiceURL": "https://example.com/terms",
309 "defaultPrompt": [
310 "Use My Plugin to summarize new CRM notes.",
311 "Use My Plugin to triage new customer follow-ups."
312 ],
313 "brandColor": "#10A37F",
314 "composerIcon": "./assets/icon.png",
315 "logo": "./assets/logo.png",
316 "screenshots": ["./assets/screenshot-1.png"]
317 }
318}
319```
320
321`.codex-plugin/plugin.json` is the required entry point. The other manifest
322fields are optional, but published plugins commonly use them.
323
324### Manifest fields
325
326Use the top-level fields to define package metadata and point to bundled
327components:
328
329- `name`, `version`, and `description` identify the plugin.
330- `author`, `homepage`, `repository`, `license`, and `keywords` provide
331 publisher and discovery metadata.
332- `skills`, `mcpServers`, and `apps` point to bundled components relative to
333 the plugin root.
334- `interface` controls how install surfaces present the plugin.
335
336Use the `interface` object for install-surface metadata:
337
338- `displayName`, `shortDescription`, and `longDescription` control the title
339 and descriptive copy.
340- `developerName`, `category`, and `capabilities` add publisher and capability
341 metadata.
342- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` provide external
343 links.
344- `defaultPrompt`, `brandColor`, `composerIcon`, `logo`, and `screenshots`
345 control starter prompts and visual presentation.
346
347### Path rules
348
349- Keep manifest paths relative to the plugin root and start them with `./`.
350- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under
351 `./assets/` when possible.
352- Use `skills` for bundled skill folders, `apps` for `.app.json`, and
353 `mcpServers` for `.mcp.json`.
354
355### Publish official public plugins
356
357Adding plugins to the official Plugin Directory is coming soon.
358
359Self-serve plugin publishing and management are coming soon.