plugins/build.md Codex Docs, 2026-04-25 06:37 UTC → 2026-05-02 06:45 UTC

304 304 

305Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include305Every 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 or306a `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 to307connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,

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

309 309 

310- my-plugin/310- my-plugin/

311 311 

319 - SKILL.md Optional: skill instructions319 - SKILL.md Optional: skill instructions

320 - .app.json Optional: app or connector mappings320 - .app.json Optional: app or connector mappings

321 - .mcp.json Optional: MCP server configuration321 - .mcp.json Optional: MCP server configuration

322 - hooks/

323 

324 - hooks.json Optional: lifecycle configuration

322 - assets/ Optional: icons, logos, screenshots325 - assets/ Optional: icons, logos, screenshots

323 326 

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

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

326 329 

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

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

351 "skills": "./skills/",354 "skills": "./skills/",

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

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

357 "hooks": "./hooks/hooks.json",

354 "interface": {358 "interface": {

355 "displayName": "My Plugin",359 "displayName": "My Plugin",

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

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

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

386 publisher and discovery metadata.390 publisher and discovery metadata.

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

388 the plugin root.392 relative to the plugin root.

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

390 394 

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

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

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

406 `./assets/` when possible.410 `./assets/` when possible.

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

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

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

414 that default lifecycle config automatically.

415 

416### Bundled MCP servers and lifecycle config

417 

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

419server map or a wrapped `mcp_servers` object.

420 

421Direct server map:

422 

423```json

424{

425 "docs": {

426 "command": "docs-mcp",

427 "args": ["--stdio"]

428 }

429}

430```

431 

432Wrapped server map:

433 

434```json

435{

436 "mcp_servers": {

437 "docs": {

438 "command": "docs-mcp",

439 "args": ["--stdio"]

440 }

441 }

442}

443```

444 

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

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

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

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

409 449 

410### Publish official public plugins450### Publish official public plugins

411 451