feat: add Codex plugin support without duplicating skills

[federicobartoli]

Summary

Make this repo installable as a Codex plugin with a single command, while keeping skills/ as the single source of truth shared with Claude Code. No files are copied, no installer script, no wrapper skills.

codex marketplace add addyosmani/agent-skills

What this adds

• codex/.codex-plugin/plugin.json — Codex manifest ("skills": "./skills/").
• codex/skills — git-tracked symlink to ../skills (9 bytes, mode 120000). Keeps the plugin directory self-contained without duplicating any skill content.
• .agents/plugins/marketplace.json — marketplace entry declaring the plugin at ./codex.
• docs/codex-setup.md — install and usage guide, including a fallback that replaces the symlink with a local copy for Windows users.

Net change: 4 files, ~78 lines, 0 duplicated skill content.

Why no duplication

Codex and Claude Code share the same SKILL.md format (YAML frontmatter with name + description). The Codex plugin docs define skills as a relative path to a folder; pointing it at the existing skills/ via a symlink means one file serves both platforms.

.claude/commands/ and agents/ stay Claude-specific — Codex natively supports only skills, apps, and MCP servers, so bundling commands/personas inside a Codex plugin isn't meaningful. Codex users invoke skills directly.

Why a codex/ subdirectory

Codex's manifest validator rejects plugins at the marketplace root: source.path must start with ./ and stay inside the marketplace root. codex/ is that subdirectory.

Verified

Tested with codex-cli 0.121.0:

• codex marketplace add federicobartoli/agent-skills@feat/codex-plugin-support succeeds.
• Plugin registered in ~/.codex/config.toml, cached under ~/.codex/plugins/cache/agent-skills/.
• All 21 skills visible in the plugin's Skills list via the Codex UI.

Open to alternatives

If a symlink in the repo is undesirable, I'm happy to switch to either:

• Restructure — git mv skills codex/skills and point Claude Code's plugin.json at the new path (no symlink, but larger diff moving 21 directories), or
• Manual step — drop the symlink and document a cp -R skills codex/skills step after git clone (no symlink, but install is no longer a single codex marketplace add).

Just let me know which direction you prefer.

Relation to #82

Lighter-weight alternative to #82 (which adds ~900 lines: installer script, wrapper skills regenerated from .claude/commands/, bundled copies of skills//references//agents/). Same intent; here Codex reads the existing skills/ directly. Happy to defer to whichever direction the maintainer prefers.

Test plan

• codex marketplace add federicobartoli/agent-skills@feat/codex-plugin-support succeeds
• Marketplace appears in ~/.codex/config.toml
• Plugin cache created under ~/.codex/plugins/cache/agent-skills/
• All 21 skills visible in Codex UI under the plugin's Skills list
• Skills invokable in chat after UI install (pending maintainer verification)

Next ideas: consider auto-generating (?) or at least avoiding repetition of the manifest; also consider enriching the manifest with marketplace metadata (https://developers.openai.com/codex/plugins/build#marketplace-metadata
).

[brandonxiang]

why not to have claude commands like "spec", "plan", "build", "test", "review", "ship" inside codex？

[ryankert01]

support to add skill in codex more smoothly. I personally want to use it.

[ryankert01]

nit: I think also need to update readme for QuickStart?

[federicobartoli]

yes, thank u man, i'll make the change as soon as I can :D

[federicobartoli]

Pushed d70d7a8 to update the install command for Codex CLI v0.122+.

In Codex CLI 0.122 the marketplace subcommand moved from codex marketplace to codex plugin marketplace (verified on 0.128.0). The README and docs/codex-setup.md now use codex plugin marketplace add addyosmani/agent-skills. The plugin manifest and marketplace.json schemas are unchanged — only the user-facing install command was renamed.

Test plan still valid; just substitute the new subcommand:

codex plugin marketplace add federicobartoli/agent-skills@feat/codex-plugin-support