---
title: "feat: Ship Codex-format plugin manifests alongside Claude manifests"
description: "Add Codex-format plugin manifests (`.agents/plugins/marketplace.json` plus per-plugin `.codex-plugin/plugin.json`) to the repo alongside the existing Claude-format manifests, so Codex users can install CE's skills via the native `codex plugin marketplace add EveryInc/compound-engineering-plugin` flow."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/2026-04-20-001-feat-codex-native-plugin-manifests-plan
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T10:59:10.057Z
license: CC-BY-4.0
attribution: "feat: Ship Codex-format plugin manifests alongside Claude manifests — Claudary (https://claudary.paisolsolutions.com/skills/2026-04-20-001-feat-codex-native-plugin-manifests-plan)"
---

# feat: Ship Codex-format plugin manifests alongside Claude manifests
Add Codex-format plugin manifests (`.agents/plugins/marketplace.json` plus per-plugin `.codex-plugin/plugin.json`) to the repo alongside the existing Claude-format manifests, so Codex users can install CE's skills via the native `codex plugin marketplace add EveryInc/compound-engineering-plugin` flow.

## Overview

---
title: "feat: Ship Codex-format plugin manifests alongside Claude manifests"
type: feat
status: active
date: 2026-04-20
---

# feat: Ship Codex-format plugin manifests alongside Claude manifests

## Overview

Add Codex-format plugin manifests (`.agents/plugins/marketplace.json` plus per-plugin `.codex-plugin/plugin.json`) to the repo alongside the existing Claude-format manifests, so Codex users can install CE's skills via the native `codex plugin marketplace add EveryInc/compound-engineering-plugin` flow.

Agents are not supported by Codex's native plugin spec, so the existing Bun converter (`bunx @every-env/compound-plugin install compound-engineering --to codex`) remains required to complete a CE install. To prevent skill double-registration when users run both flows, the Bun converter's `--to codex` default is changed to **agents-only**; an opt-in `--include-skills` flag re-enables the full bundle for standalone installs. The README documents the two-step flow.

## Problem Frame

Codex is the only target in CE's installable set still gated on the Bun converter for the baseline (skills) install. Every other tool either has native support (Claude Code, Cursor, Copilot, Droid, Qwen) or has no native install mechanism at all (OpenCode, Pi, Gemini, Kiro). Codex does have a native plugin format — we just never shipped the manifests for it.

Shipping the Codex manifests:

* Puts Codex in the "native install" tier alongside Copilot/Droid/Qwen for discovery and lifecycle (install/uninstall/update via `codex plugin`)

* Does not change the agent install path (native Codex plugin install does not register custom agents per the spec and our empirical test)

* Costs \\~two hand-authored JSON files per plugin plus a small release-infra extension, because the repo already supports dual-format manifests (Claude + Cursor) and adding a third format is a parallel entry, not a new pattern

## Requirements Trace

* R1. `codex plugin marketplace add <local-clone>` must succeed and register the CE plugin

* R2. `codex plugin install compound-engineering` must install CE's skills into the expected Codex skill location

* R3. Plugin version in `.codex-plugin/plugin.json` must stay in sync with `.claude-plugin/plugin.json` automatically on release

* R4. `bun run release:validate` must fail if the Codex manifests drift out of sync with the Claude manifests (plugin list mismatch, name mismatch, version mismatch)

* R5. README documents the Codex native install flow with a followup step for agents

* R6. No regressions to existing Claude, Cursor, Copilot, Droid, Qwen, or Bun-converter install paths

## Scope Boundaries

* Native Codex plugin install handles skills only (Codex spec does not register custom agents or slash commands). Agents still flow through the Bun converter; the converter's default behavior is changed in Unit 9 so skills are NOT emitted by default, preventing double-registration.

* Commands are not installed via native Codex plugin install (Codex spec limitation). Only affects the `coding-tutor` plugin, which ships commands. Coding-tutor users wanting commands run the Bun converter with `--include-skills`.

* No single-command hybrid UX (the two-step `codex plugin install` + `bunx ... --to codex` flow is documented, not automated). This becomes obsolete when Codex supports custom agents natively — at which point the entire `--to codex` converter path is deprecated.

* No logo asset — `interface.logo` is omitted; can be added in a followup when a branded icon is available

* No Codex-specific skill frontmatter fields (`metadata.priority`, `metadata.pathPatterns`, `metadata.bashPatterns`) — these are trigger-tuning extensions, not required for registration, and can be added per-skill in followups

* No empirical test of remote-repo install in this plan. The remote `codex plugin marketplace add EveryInc/compound-engineering-plugin` flow documented in the README cannot be tested from a feature branch — Codex fetches the default branch of the remote. Remote-install verification is a separate manual step immediately post-merge, before the release tag: clone the merged `main`, run the remote install command against it, confirm skills register. If the remote path fails, ship a fix-forward PR rather than rolling back. `source: { source: "local", path: "./plugins/<name>" }` has been empirically verified as the correct schema for both bundled AND remote-cloned marketplaces (see Resolved Open Questions), so the most likely remote-vs-local divergence — the schema — is already de-risked

### Deferred to Separate Tasks

* Hybrid install UX that bundles `codex plugin install` with the agent followup into a single command: future plan once Codex's native spec is more settled

* Codex-specific skill metadata tuning (priority, path patterns, bash patterns) for discoverability: evaluate per-skill in followups as use patterns emerge

* Plugin logo asset design: hand off to design; drop in later

* Removal of the `--to codex` Bun converter path entirely once Codex supports custom agents natively; at that point `codex plugin install` is sufficient on its own

## Context & Research

### Relevant Code and Patterns

* `.claude-plugin/marketplace.json`, `.cursor-plugin/marketplace.json` — existing dual-format marketplace manifests (Cursor mirrors Claude's schema; Codex will diverge)

* `plugins/compound-engineering/.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json` — existing dual plugin manifests (source of truth for name/description/version/author/homepage/keywords)

* `.github/release-please-config.json` — `plugins/compound-engineering` and `plugins/coding-tutor` packages already list `extra-files` for `.claude-plugin/plugin.json` and `.cursor-plugin/plugin.json`; Codex adds a third entry in each

* `.github/.release-please-manifest.json` — tracks versions per release-please package; Cursor marketplace (`.cursor-plugin`) is a separate tracked package, Codex likely does not need its own tracked package since the Codex marketplace spec has no `version` field (see Key Technical Decisions)

* `src/release/components.ts` — declares release components (`marketplace`, `cursor-marketplace`, CLI, per-plugin) and their source-of-truth file paths

* `src/release/metadata.ts` — sync engine that reads the various marketplace + plugin manifests and cross-checks / updates versions and descriptions

* `src/release/config.ts` — validator stubs (currently only checks `changelog-path` shape); extend here or in `metadata.ts` for Codex-consistency rules

* `scripts/release/validate.ts` — entry point run by `bun run release:validate`; consumes the above

* `tests/release-components.test.ts`, `tests/release-config.test.ts`, `tests/release-metadata.test.ts` — existing test coverage for the release infra; extend alongside the code changes

### External References

* Codex plugin docs: [developers.openai.com/codex/plugins](https://developers.openai.com/codex/plugins), [developers.openai.com/codex/plugins/build](https://developers.openai.com/codex/plugins/build)

* Canonical reference repo: `github.com/openai/plugins` — confirms `.agents/plugins/marketplace.json` at repo root, `.codex-plugin/plugin.json` per plugin

* Local evidence:

  * `~/.codex/.tmp/bundled-marketplaces/openai-bundled/.agents/plugins/marketplace.json` — bundled OpenAI example, minimal shape

  * `~/.codex/.tmp/plugins/plugins/vercel/` — fully-featured plugin with skills; shows `"skills": "./skills/"` declaration pattern and `interface{}` block shape

### Documented Codex format (worked out from sources above)

**`.agents/plugins/marketplace.json`** (repo root; Codex looks here after cloning):

```json
{
  "name": "compound-engineering-plugin",
  "interface": { "displayName": "Compound Engineering" },
  "plugins": [
    {
      "name": "compound-engineering",
      "source": { "source": "local", "path": "./plugins/compound-engineering" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Coding"
    }
  ]
}
```

**`plugins/<name>/.codex-plugin/plugin.json`**:

```json
{
  "name": "...",
  "version": "...",
  "description": "...",
  "author": { "name": "...", "email": "...", "url": "..." },
  "homepage": "...",
  "repository": "...",
  "license": "...",
  "keywords": ["..."],
  "skills": "./skills/",
  "interface": {
    "displayName": "...",
    "shortDescription": "...",
    "longDescription": "...",
    "developerName": "...",
    "category": "Coding",
    "capabilities": ["Interactive", "Read", "Write"],
    "websiteURL": "...",
    "privacyPolicyURL": "...",
    "termsOfServiceURL": "...",
    "defaultPrompt": ["..."],
    "screenshots": []
  }
}
```

Required fields per docs: `name`, `version`, `description`. All others optional. Native install registers skills (via `skills:` key), MCP servers (`mcpServers:`), apps (`apps:`), hooks (`hooks:`). Agents, commands, and prompts are not declarable or auto-discovered.

## Key Technical Decisions

* **Commit manifests, don't generate.** Hand-authored, versioned like source. release-please bumps `version` in `.codex-plugin/plugin.json` via `extra-files`, same mechanism already used for Claude + Cursor.

* **Don't track the Codex marketplace as a release-please package.** The Codex marketplace spec (`.agents/plugins/marketplace.json`) has no `version` field — unlike the Claude and Cursor marketplaces which have `metadata.version`. Treat the Codex marketplace as static content; only the per-plugin `.codex-plugin/plugin.json` version needs automated bumping.

* **Extend** **`src/release/metadata.ts`** **to read the Codex manifests and cross-check them.** Mirrors how Cursor manifests were added: read them, cross-reference plugin lists and versions against the Claude source of truth, fail validation on drift.

* **Omit** **`interface.logo`** **for now.** Optional per docs; the bundled OpenAI example has one but many listed plugins don't. Ship without, add later when an icon is available.

* **Don't add Codex-specific skill frontmatter extensions.** `metadata.priority`, `metadata.pathPatterns`, `metadata.bashPatterns` are trigger-tuning optimizations, not required for registration. CE skills will use their current Claude-compatible frontmatter; Codex will register them with default trigger behavior.

* **`coding-tutor`** **still needs a Codex manifest** even though native install won't handle its commands. Reason: the marketplace lists both plugins as a unit; omitting coding-tutor from the Codex marketplace would be asymmetric with the Claude marketplace. Native install will successfully install coding-tutor's skills but not its commands — the README's coding-tutor install instructions will note that commands require the Bun converter.

* **Validation failure modes to enforce:** missing Codex manifest when Claude manifest exists; plugin list mismatch between `.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json`; name mismatch between paired plugin.json files; version mismatch between paired plugin.json files; declared `skills: "./skills/"` pointing at a missing directory.

## Open Questions

### Resolved During Planning

* **Do we need to ship a logo?** No — omit the field. Add in a followup when an asset is available.

* **Should skills declare Codex metadata extensions?** No — ship with default trigger behavior. Add per-skill tuning in followups if use patterns reveal a need.

* **Is the Codex marketplace a release-please package?** No — it has no version field per the Codex spec, so it stays static. Per-plugin `.codex-plugin/plugin.json` is the only versioned file.

* **Does** **`coding-tutor`** **get a Codex manifest?** Yes — marketplace parity with Claude. Native install will register its skills but not its commands; README notes the gap.

* **Are file paths for the** **`skills:`** **declaration plugin-relative or marketplace-relative?** Plugin-relative. `"skills": "./skills/"` in `plugins/compound-engineering/.codex-plugin/plugin.json` means `plugins/compound-engineering/skills/`. Confirmed via vercel and github plugin examples.

* **Does the `source: "local"` marketplace schema work for remote-cloned marketplaces, not just bundled ones?** Yes. The `openai-curated` marketplace (a real-world remote-fetched marketplace Codex clones and caches at `~/.codex/.tmp/plugins/.agents/plugins/marketplace.json`) uses the identical `source: { source: "local", path: "./plugins/<name>" }` schema. "local" refers to the plugin's co-location within the marketplace repo, not "bundled with Codex." Same schema for both.

* **Does Codex's default skill discovery find flat `skills/<name>/SKILL.md` layouts at CE's depth?** Yes. Vercel's reference plugin at `~/.codex/.tmp/plugins/plugins/vercel/skills/` uses the exact layout CE ships — flat subdirectories each containing `SKILL.md`. CE has 43 skill directories at that depth under `plugins/compound-engineering/skills/`. Unit 7 includes a count-based assertion to catch partial-discovery regressions.

### Deferred to Implementation

* **Exact** **`interface.shortDescription`** **/** **`longDescription`** **copy for each plugin.** Use the `description` from `.claude-plugin/plugin.json` as the short form; compose a longer version from the plugin's README section or existing marketplace description. Can be refined during implementation.

* **Does** **`codex plugin install`** **succeed against a local clone of this branch?** Empirical verification happens during implementation. If the plugin manifest schema is rejected (e.g., a required field we didn't identify from docs), iterate.

* **Does the Codex skills mechanism register CE's skills without modification?** Local empirical test during implementation. CE skills use standard Claude frontmatter (`name`, `description`); Codex docs say those are the required fields. Expected to work.

## Implementation Units

* [ ] **Unit 1: Author** **`plugins/compound-engineering/.codex-plugin/plugin.json`**

**Goal:** Codex plugin manifest for the primary CE plugin, with skills declared and interface metadata populated.

**Requirements:** R1, R2

**Dependencies:** None

**Files:**

* Create: `plugins/compound-engineering/.codex-plugin/plugin.json`

**Approach:**

* Read the Claude manifest at `plugins/compound-engineering/.claude-plugin/plugin.json` for source-of-truth fields (name, version, description, author, homepage, license, keywords).

* Add Codex-specific fields: `skills: "./skills/"`, and an `interface{}` block with `displayName`, `shortDescription` (reuse `description`), `longDescription` (1-2 sentence pitch, can draw from README lead paragraph), `developerName` (derive from author), `category: "Coding"`, `capabilities: ["Interactive", "Read", "Write"]`, `websiteURL: homepage`, `privacyPolicyURL` / `termsOfServiceURL` (reuse Every's existing policy URLs if available; omit otherwise — optional per docs), `defaultPrompt: []` (can leave empty or add 2-3 starter prompts).

* Omit `logo` (decided in Key Technical

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/2026-04-20-001-feat-codex-native-plugin-manifests-plan) · https://claudary.paisolsolutions.com