Skip to content
Skills Library
AI & agents · Building & coding

codex-desktop-plugins

/codex-desktop-plugins

Package, install, test, share and submit plugins for the ChatGPT desktop app (formerly the Codex app): the portable plugin.json or .codex-plugin layout, extensions.com.openai settings, bundled skills and MCP servers, hooks, marketplace.json, install cache paths, .codex/config.toml, workspace publish and public directory submission. Use when the user wants to create, ship or debug a ChatGPT or Codex desktop plugin and needs its requirements.

Repository
mental ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Package, install, test, share and submit plugins for the ChatGPT desktop app (formerly the Codex app): the portable plugin.json or .codex-plugin layout, extensions.com.openai settings, bundled skills and MCP servers, hooks, marketplace.json, install cache paths, .codex/config.toml, workspace publish and public directory submission. Use when the user wants to create, ship or debug a ChatGPT or Codex desktop plugin and needs its requirements.

Original author description

Package, install, test, share and submit plugins for the ChatGPT desktop app (formerly the Codex app): the portable plugin.json or .codex-plugin layout, extensions.com.openai settings, bundled skills and MCP servers, hooks, marketplace.json, install cache paths, .codex/config.toml, workspace publish and public directory submission. Use when the user wants to create, ship or debug a ChatGPT or Codex desktop plugin and needs its requirements.

How it works

  1. Requirements
  2. Layouts
  3. Workflow
  4. Hooks
  5. Safety
  6. Verification checklist
  7. Anti-patterns
  8. Pointers
Original SKILL.md headings · 86 lines, 729 words
SKILL.md preview
---
name: codex-desktop-plugins
description: >-
  Package, install, test, share and submit plugins for the ChatGPT desktop app
  (formerly the Codex app): the portable plugin.json or .codex-plugin layout,
  extensions.com.openai settings, bundled skills and MCP servers, hooks,
  marketplace.json, install cache paths, .codex/config.toml, workspace publish
  and public directory submission. Use when the user wants to create, ship or
  debug a ChatGPT or Codex desktop plugin and needs its requirements.
license: MIT
compatibility: Needs a ChatGPT desktop app with plugins enabled (macOS or native Windows). Optional Codex CLI for codex plugin marketplace commands. Public submission needs a platform.openai.com organization with verified developer identity.
metadata:
  author: Ali Farahat
  tags: chatgpt-desktop,codex,plugins,marketplace,submission
  verified-against: developers.openai.com/plugins/build/plugins and deploy/submission
when_to_use: |
  USE WHEN:
  - The user wants to create, package, install, share or submit a ChatGPT /
    Codex desktop plugin, or asks what a plugin needs (manifest, skills, MCP,
    marketplace, review test cases).
  - They mention plugin.json, .codex-plugin, .agents/plugins/marketplace.json,
    @plugin-creator, "Add custom MCP server", or plugin submission.

  DO NOT USE WHEN:
  - The task is the UI inside the plugin (entrypoints, MCP Apps): use
    codex-desktop-extensions.
  - The task is writing a SKILL.md: use codex-desktop-skills.
  - The user wants Claude Desktop plugins: use claude-desktop-plugins.
---

# ChatGPT / Codex desktop plugins

A plugin bundles **skills**, optionally an **MCP server** (tools, plus UI via `codex-desktop-extensions`), and listing metadata. Sources (re-check; they change): `https://developers.openai.com/plugins/build/plugins.md`, `.../deploy/submission.md`, `.../plugin-guidelines`, index `https://developers.openai.com/llms.txt`. The ChatGPT/Codex docs live at `https://learn.chatgpt.com/docs/`.

## Requirements

1. A manifest at the plugin root, in one of two accepted formats (below).
2. Every path in the manifest starts with `./`, is relative to the plugin root and stays inside it.
3. Skills in `skills/<name>/SKILL.md` (auto-discovered), each with `name` and `description`.
4. If it has tools: an MCP config declaring one or more servers.
5. Listing metadata (`interface`): name, descriptions, developer, category, icons.
6. For public submission: `review` test cases (5 positive, 3 negative), a walkthrough video URL, release notes, privacy and terms URLs, a public HTTPS MCP server and a verified domain.

## Layouts

**Portable Agent Plugins format** (preferred for new work): root `plugin.json` with `$schema`, OpenAI-specific settings under `extensions.com.openai`, `skills/`, `mcp.json`.

**Codex compat format** (still supported; what `@plugin-creator` scaffolds): `.codex-plugin/plugin.json` with `skills`, `mcpServers` and a root `interface` block, plus `.mcp.json` (no `$schema`, no `type`). Onboarding, review and publication stay under `extensions.com.openai`. When `extensions.com.openai` is an object it **fully replaces** the `.codex-plugin` overlay; the two are not merged.

Claude-style manifests and `.claude-plugin/marketplace.json` are accepted too. Field tables and examples: [references/manifest.md](references/manifest.md).

```text
acme-notes/
  plugin.json
  mcp.json
  assets/        icons, logo, screenshots
  skills/<name>/SKILL.md
```

## Workflow

1. **Scaffold** with `@plugin-creator` (Work mode) or `$plugin-creator` (Codex), or by hand from [references/manifest.md](references/manifest.md). Use a stable kebab-case `name`; it is the identity.
2. **Add skills** (`codex-desktop-skills`) and, if needed, the MCP server and UI (`codex-desktop-extensions`).
3. **Add a marketplace entry** to install locally: [references/marketplaces-and-install.md](references/marketplaces-and-install.md).
4. **Restart the desktop app.** It loads from `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`.
5. **Test** skills with direct, indirect and negative prompts; test MCP tools and UI entrypoints.
6. **Share**: repo marketplace for a team, workspace publish for an organization, or public submission: [references/submission.md](references/submission.md).
7. **Bump `version`** for every release; changed packages need a new ZIP when submitted.

## Hooks

`hooks/hooks.json` is discovered by default; an explicit manifest `hooks` value replaces default discovery. Env vars: `PLUGIN_ROOT`, `PLUGIN_DATA` (and `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`). Hooks apply only to manually installed desktop plugins and are skipped until the user reviews and trusts them. **A plugin with hooks cannot be submitted to the public directory**; remove them before submission. Docs: `https://learn.chatgpt.com/docs/hooks`.

## Safety

- Never put secrets, tokens or credentials in the plugin folder or ZIP. Use per-user auth (`policy.authentication`) and server-side secrets.
- Hooks execute shell commands; keep them minimal, document them and never run them silently.
- Keep marketplace `source.path` inside the marketplace root; never point it at `..` or absolute paths.
- Do not ask reviewers to run private-network or MFA-gated setups; supply credentials without MFA.
- MCP tool approval: set conservative `default_tools_approval_mode` and per-tool `approval_mode` for destructive tools.
- Do not tag, publish or submit on the user's behalf without explicit confirmation.

## Verification checklist

- [ ] Manifest parses as JSON; all paths begin with `./` and resolve inside the plugin
- [ ] `name` is stable kebab-case; `version` bumped
- [ ] Each skill has `name` and a trigger-rich `description`
- [ ] `extensions.com.openai` chosen deliberately (it replaces the `.codex-plugin` overlay)
- [ ] MCP config valid; at most one remote MCP server if submitting
- [ ] No hooks and no `apps`/`.app.json` references if submitting to the public directory
- [ ] Marketplace entry has `name`, `source`, `policy`, `category`
- [ ] Reinstalled and app restarted after changes
- [ ] 5 positive and 3 negative review cases, video, release notes (submission)
- [ ] No secrets anywhere in the package

## Anti-patterns

- Editing the cache directory instead of the source plugin.
- Mixing `.codex-plugin/plugin.json` overlay fields with `extensions.com.openai` and expecting a merge.
- Absolute paths or `../` in manifest or marketplace paths.
- Shipping hooks and then submitting to the public directory.
- Adding an MCP server to an already published skills-only plugin (unsupported; changing the server URL needs support).
- Vague skill descriptions, so skills never trigger.
- Changing `name` between versions (breaks identity and installs).

## Pointers

| Need | Read |
| --- | --- |
| Manifest fields, examples, MCP config | [references/manifest.md](references/manifest.md) |
| Marketplaces, install cache, config.toml, CLI | [references/marketplaces-and-install.md](references/marketplaces-and-install.md) |
| Workspace publish, public submission, review | [references/submission.md](references/submission.md) |
| UI entrypoints and MCP Apps | `codex-desktop-extensions` |
| SKILL.md authoring | `codex-desktop-skills` |
Files in this package (4)
  • SKILL.md 7 KB
  • references/manifest.md 4 KB
  • references/marketplaces-and-install.md 3 KB
  • references/submission.md 2 KB

Versions

The database has no other skills named codex-desktop-plugins.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 6df964ce3897 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90Codex CLI Plugins
    This skill should be used when the user asks to "create a Codex plugin", "build a plugin for Codex CLI", "package a Codex skill", "set up a Codex marketplace", "publish a Codex plugin", "configure plugin.json manifest", "add MCP to a Codex plugin", "install a local plugin in…
  • 100codex-desktop-skills
    Author Agent Skills for the ChatGPT desktop app (formerly the Codex app): SKILL.md frontmatter, trigger-rich descriptions, references/assets/scripts layout, agents/openai.yaml MCP tool dependencies, @skill-creator, and activation testing with direct, indirect, incomplete,…
  • 100claude-desktop-plugins
    Create, validate, and publish Claude plugins for Claude Desktop (Chat, Cowork, Code tab) and Claude Code: .claude-plugin/plugin.json, skills, commands, agents, hooks, MCP and LSP servers, userConfig, marketplaces and the Anthropic directory. Use when the user asks how to build a…
  • 90Claude Code Plugin Builder
    Creates Claude Code plugins with proper manifest structure, directory layout, and components (commands, agents, skills, hooks, MCP servers). This is for Claude Code plugins (`.claude-plugin/plugin.json`) — for Codex plugins (`.codex-plugin/plugin.json`) use the `plugin-creator`…
  • 100publish-skills
    Publish agent skills AND MCP servers to every marketplace, plugin directory, and registry — security-scan for private data, validate with `gh skill`, cut a release, wire the Claude /plugin and Codex marketplaces, publish an MCP server to the official MCP Registry (mcp-publisher…
  • 95plugin-writer
    Create new Claude Code plugins from scratch with proper directory structure (.claude-plugin/plugin.json, skills/, agents/), or add existing plugins to marketplace.json. Use when creating a plugin, setting up plugin metadata, configuring MCP servers, or adding plugins to a marketplace.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.