plugins/build.md Codex Docs, 2026-05-02 00:48 UTC → 2026-05-05 23:00 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

307connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,341connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,

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

309 343 

310- my-plugin/344<FileTree

311 345 class="mt-4"

312 - .codex-plugin/346 tree={[

313 347 {

314 - plugin.json Required: plugin manifest348 name: "my-plugin/",

315 - skills/349 open: true,

316 350 children: [

317 - my-skill/351 {

318 352 name: ".codex-plugin/",

319 - SKILL.md Optional: skill instructions353 open: true,

320 - .app.json Optional: app or connector mappings354 children: [

321 - .mcp.json Optional: MCP server configuration355 {

322 - hooks/356 name: "plugin.json",

323 357 comment: "Required: plugin manifest",

324 - hooks.json Optional: lifecycle configuration358 },

325 - assets/ Optional: icons, logos, screenshots359 ],

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/>

326 403 

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

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