plugins/build.md Codex Docs, 2026-04-23 12:28 UTC → 2026-05-07 20:02 UTC

10 10 

11For the fastest setup, use the built-in `$plugin-creator` skill.11For the fastest setup, use the built-in `$plugin-creator` skill.

12 12 

13![plugin-creator skill in Codex](/images/codex/plugins/plugin-creator.png)13<CodexScreenshot

14 alt="plugin-creator skill in Codex"

15 lightSrc="/images/codex/plugins/plugin-creator.png"

16 darkSrc="/images/codex/plugins/plugin-creator-dark.png"

17/>

14 18 

15It scaffolds the required `.codex-plugin/plugin.json` manifest and can also19It scaffolds the required `.codex-plugin/plugin.json` manifest and can also

16generate a local marketplace entry for testing. If you already have a plugin20generate a local marketplace entry for testing. If you already have a plugin

17folder, you can still use `$plugin-creator` to wire it into a local21folder, you can still use `$plugin-creator` to wire it into a local

18marketplace.22marketplace.

19 23 

20![how to invoke the plugin-creator skill](/images/codex/plugins/plugin-creator-invoke.png)24<CodexScreenshot

25 alt="how to invoke the plugin-creator skill"

26 lightSrc="/images/codex/plugins/plugin-creator-invoke.png"

27 darkSrc="/images/codex/plugins/plugin-creator-invoke-dark.png"

28/>

21 29 

22### Build your own curated plugin list30### Build your own curated plugin list

23 31 

38single plugin while you are testing, then grow into a larger curated catalog as46single plugin while you are testing, then grow into a larger curated catalog as

39you add more plugins.47you add more plugins.

40 48 

41![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)49<CodexScreenshot

50 alt="custom local marketplace in the plugin directory"

51 lightSrc="/images/codex/plugins/codex-local-plugin-light.png"

52 darkSrc="/images/codex/plugins/codex-local-plugin.png"

53/>

42 54 

43### Add a marketplace from the CLI55### Add a marketplace from the CLI

44 56 

119Use a repo marketplace or a personal marketplace, depending on who should be131Use a repo marketplace or a personal marketplace, depending on who should be

120able to access the plugin or curated list.132able to access the plugin or curated list.

121 133 

134<Tabs

135 id="codex-plugins-local-install"

136 param="install-scope"

137 defaultTab="workspace"

138 tabs={[

139 {

140 id: "workspace",

141 label: "Repo",

142 },

143 {

144 id: "global",

145 label: "Personal",

146 },

147 ]}

148>

149 <div slot="workspace">

122 Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`150 Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`

123 and store your plugins under `$REPO_ROOT/plugins/`.151 and store your plugins under `$REPO_ROOT/plugins/`.

124 152 

157 185 

158 Step 3: Restart Codex and verify that the plugin appears.186 Step 3: Restart Codex and verify that the plugin appears.

159 187 

188 </div>

189 

190 <div slot="global">

160 Add a marketplace file at `~/.agents/plugins/marketplace.json` and store191 Add a marketplace file at `~/.agents/plugins/marketplace.json` and store

161 your plugins under `~/.codex/plugins/`.192 your plugins under `~/.codex/plugins/`.

162 193 

174 205 

175 Step 3: Restart Codex and verify that the plugin appears.206 Step 3: Restart Codex and verify that the plugin appears.

176 207 

208 </div>

209</Tabs>

210 

177The marketplace file points to the plugin location, so those directories are211The marketplace file points to the plugin location, so those directories are

178examples rather than fixed requirements. Codex resolves `source.path` relative212examples rather than fixed requirements. Codex resolves `source.path` relative

179to the marketplace root, not relative to the `.agents/plugins/` folder. See213to the marketplace root, not relative to the `.agents/plugins/` folder. See

304 338 

305Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include339Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include

306a `skills/` directory, an `.app.json` file that points at one or more apps or340a `skills/` directory, an `.app.json` file that points at one or more apps or

307connectors, an `.mcp.json` file that configures MCP servers, and assets used to341connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,

308present the plugin across supported surfaces.342and assets used to present the plugin across supported surfaces.

309 

310- my-plugin/

311 343 

312 - .codex-plugin/344<FileTree

313 345 class="mt-4"

314 - plugin.json Required: plugin manifest346 tree={[

315 - skills/347 {

316 348 name: "my-plugin/",

317 - my-skill/349 open: true,

318 350 children: [

319 - SKILL.md Optional: skill instructions351 {

320 - .app.json Optional: app or connector mappings352 name: ".codex-plugin/",

321 - .mcp.json Optional: MCP server configuration353 open: true,

322 - assets/ Optional: icons, logos, screenshots354 children: [

355 {

356 name: "plugin.json",

357 comment: "Required: plugin manifest",

358 },

359 ],

360 },

361 {

362 name: "skills/",

363 open: true,

364 children: [

365 {

366 name: "my-skill/",

367 open: true,

368 children: [

369 {

370 name: "SKILL.md",

371 comment: "Optional: skill instructions",

372 },

373 ],

374 },

375 ],

376 },

377 {

378 name: ".app.json",

379 comment: "Optional: app or connector mappings",

380 },

381 {

382 name: ".mcp.json",

383 comment: "Optional: MCP server configuration",

384 },

385 {

386 name: "hooks/",

387 open: true,

388 children: [

389 {

390 name: "hooks.json",

391 comment: "Optional: lifecycle configuration",

392 },

393 ],

394 },

395 {

396 name: "assets/",

397 comment: "Optional: icons, logos, screenshots",

398 },

399 ],

400 },

401 ]}

402/>

323 403 

324Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,404Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,

325`.mcp.json`, and `.app.json` at the plugin root.405`.mcp.json`, `.app.json`, and lifecycle config files at the plugin root.

326 406 

327Published plugins typically use a richer manifest than the minimal example that407Published plugins typically use a richer manifest than the minimal example that

328appears in quick-start scaffolds. The manifest has three jobs:408appears in quick-start scaffolds. The manifest has three jobs:

351 "skills": "./skills/",431 "skills": "./skills/",

352 "mcpServers": "./.mcp.json",432 "mcpServers": "./.mcp.json",

353 "apps": "./.app.json",433 "apps": "./.app.json",

434 "hooks": "./hooks/hooks.json",

354 "interface": {435 "interface": {

355 "displayName": "My Plugin",436 "displayName": "My Plugin",

356 "shortDescription": "Reusable skills and apps",437 "shortDescription": "Reusable skills and apps",

384- `name`, `version`, and `description` identify the plugin.465- `name`, `version`, and `description` identify the plugin.

385- `author`, `homepage`, `repository`, `license`, and `keywords` provide466- `author`, `homepage`, `repository`, `license`, and `keywords` provide

386 publisher and discovery metadata.467 publisher and discovery metadata.

387- `skills`, `mcpServers`, and `apps` point to bundled components relative to468- `skills`, `mcpServers`, `apps`, and `hooks` point to bundled components

388 the plugin root.469 relative to the plugin root.

389- `interface` controls how install surfaces present the plugin.470- `interface` controls how install surfaces present the plugin.

390 471 

391Use the `interface` object for install-surface metadata:472Use the `interface` object for install-surface metadata:

404- Keep manifest paths relative to the plugin root and start them with `./`.485- Keep manifest paths relative to the plugin root and start them with `./`.

405- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under486- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under

406 `./assets/` when possible.487 `./assets/` when possible.

407- Use `skills` for bundled skill folders, `apps` for `.app.json`, and488- Use `skills` for bundled skill folders, `apps` for `.app.json`,

408 `mcpServers` for `.mcp.json`.489 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle config.

490- If you omit `hooks` and the plugin includes `./hooks/hooks.json`, Codex loads

491 that default lifecycle config automatically.

492 

493### Bundled MCP servers and lifecycle config

494 

495`mcpServers` can point to an `.mcp.json` file that contains either a direct

496server map or a wrapped `mcp_servers` object.

497 

498Direct server map:

499 

500```json

501{

502 "docs": {

503 "command": "docs-mcp",

504 "args": ["--stdio"]

505 }

506}

507```

508 

509Wrapped server map:

510 

511```json

512{

513 "mcp_servers": {

514 "docs": {

515 "command": "docs-mcp",

516 "args": ["--stdio"]

517 }

518 }

519}

520```

521 

522`hooks` can point to one lifecycle JSON file, an array of lifecycle JSON files,

523an inline lifecycle object, or an array of inline lifecycle objects. File paths

524must follow the same `./`-prefixed plugin-root path rules as other manifest

525paths. If you omit the manifest field, Codex still checks `./hooks/hooks.json`.

409 526 

410### Publish official public plugins527### Publish official public plugins

411 528