📝 Document Codex marketplace support
This commit is contained in:
@@ -0,0 +1,205 @@
|
|||||||
|
# Codex Plugin Marketplace Support for Reliquary
|
||||||
|
|
||||||
|
Date: 2026-05-30
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Reliquary is already a Claude plugin marketplace, and the current Codex installation can consume it today through the existing `.claude-plugin/marketplace.json` layout. In the local Codex CLI 0.135.0-alpha.1 environment, the `reliquary` marketplace is configured from `git@git.g4b.org:dirigence/reliquary.git`, and `g4b_ai`, `gitea`, and `project-uv` are installed and enabled.
|
||||||
|
|
||||||
|
For long-term portability, Reliquary should publish a parallel Codex-native marketplace layout instead of relying on Codex's compatibility with Claude marketplace metadata. The practical target is:
|
||||||
|
|
||||||
|
- keep `.claude-plugin/marketplace.json` for Claude Code
|
||||||
|
- add `.agents/plugins/marketplace.json` for Codex
|
||||||
|
- keep each plugin's existing `.claude-plugin/plugin.json`
|
||||||
|
- add each plugin's `.codex-plugin/plugin.json`
|
||||||
|
- keep shared skill content under `plugins/<plugin>/skills/<skill>/SKILL.md`
|
||||||
|
|
||||||
|
The skill directories can remain shared between Claude and Codex. The main work is metadata and install documentation.
|
||||||
|
|
||||||
|
## Current Repository State
|
||||||
|
|
||||||
|
The repo root currently has:
|
||||||
|
|
||||||
|
- `.claude/settings.json`, which configures Claude to know the `reliquary` marketplace and enable selected plugins.
|
||||||
|
- `.claude-plugin/marketplace.json`, which declares the marketplace and four plugins: `g4b_ai`, `dioxus`, `project-uv`, and `gitea`.
|
||||||
|
- `plugins/<plugin>/.claude-plugin/plugin.json` for `g4b_ai`, `gitea`, and `project-uv`.
|
||||||
|
- shared skills under `plugins/<plugin>/skills/.../SKILL.md`.
|
||||||
|
|
||||||
|
The repo-level `CLAUDE.md` already tells Claude users that this repo is a marketplace and that workpad material lives under `docs/workpad/`.
|
||||||
|
|
||||||
|
## Observed Codex Behavior
|
||||||
|
|
||||||
|
Codex is already configured locally with:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[marketplaces.reliquary]
|
||||||
|
source_type = "git"
|
||||||
|
source = "git@git.g4b.org:dirigence/reliquary.git"
|
||||||
|
|
||||||
|
[plugins."g4b_ai@reliquary"]
|
||||||
|
enabled = true
|
||||||
|
|
||||||
|
[plugins."gitea@reliquary"]
|
||||||
|
enabled = true
|
||||||
|
|
||||||
|
[plugins."project-uv@reliquary"]
|
||||||
|
enabled = true
|
||||||
|
```
|
||||||
|
|
||||||
|
Running the local Codex binary's plugin listing showed:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Marketplace `reliquary`
|
||||||
|
g4b_ai@reliquary installed, enabled 0.1.0
|
||||||
|
dioxus@reliquary not installed
|
||||||
|
project-uv@reliquary installed, enabled 0.1.0
|
||||||
|
gitea@reliquary installed, enabled 0.1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
That proves Codex can currently discover this repo's Claude marketplace file. However, Codex's own plugin creation guidance uses `.codex-plugin/plugin.json` for plugin manifests and `.agents/plugins/marketplace.json` for marketplace files, so Reliquary should add those files explicitly rather than treating Claude metadata as the only source of truth.
|
||||||
|
|
||||||
|
## Codex-Native Marketplace Shape
|
||||||
|
|
||||||
|
OpenAI's Codex plugin creator skill describes Codex plugin scaffolds as containing a required `.codex-plugin/plugin.json`, optional `skills/`, and marketplace entries in `.agents/plugins/marketplace.json`. Its reference schema shows `skills: "./skills/"` in the plugin manifest and Codex marketplace entries with `source`, `policy`, and `category` fields.
|
||||||
|
|
||||||
|
Recommended repo-level Codex marketplace file:
|
||||||
|
|
||||||
|
```text
|
||||||
|
.agents/plugins/marketplace.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Recommended shape:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "reliquary",
|
||||||
|
"interface": {
|
||||||
|
"displayName": "Reliquary"
|
||||||
|
},
|
||||||
|
"plugins": [
|
||||||
|
{
|
||||||
|
"name": "g4b_ai",
|
||||||
|
"source": {
|
||||||
|
"source": "local",
|
||||||
|
"path": "./plugins/g4b_ai"
|
||||||
|
},
|
||||||
|
"policy": {
|
||||||
|
"installation": "AVAILABLE",
|
||||||
|
"authentication": "ON_INSTALL"
|
||||||
|
},
|
||||||
|
"category": "Productivity"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each current plugin should get a Codex manifest:
|
||||||
|
|
||||||
|
```text
|
||||||
|
plugins/g4b_ai/.codex-plugin/plugin.json
|
||||||
|
plugins/gitea/.codex-plugin/plugin.json
|
||||||
|
plugins/project-uv/.codex-plugin/plugin.json
|
||||||
|
plugins/dioxus/.codex-plugin/plugin.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Recommended minimal manifest shape:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "g4b_ai",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"description": "Gabor's personal Codex skills: workpad, research-tree, implementation-orchestration, markdown-embedded-svg.",
|
||||||
|
"author": {
|
||||||
|
"name": "Gabor Körber",
|
||||||
|
"email": "gab@g4b.org"
|
||||||
|
},
|
||||||
|
"skills": "./skills/",
|
||||||
|
"interface": {
|
||||||
|
"displayName": "g4b_ai",
|
||||||
|
"shortDescription": "Personal project workflow skills for Codex.",
|
||||||
|
"longDescription": "Workpad placement, research orchestration, implementation orchestration, and Markdown SVG guidance.",
|
||||||
|
"developerName": "Gabor Körber",
|
||||||
|
"category": "Productivity",
|
||||||
|
"capabilities": ["Skills"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The existing `.claude-plugin/plugin.json` files can stay as-is. The `.codex-plugin` files can point at the same `skills/` folders.
|
||||||
|
|
||||||
|
## How Users Would Install from Codex
|
||||||
|
|
||||||
|
Once the Codex marketplace file exists, a Codex user can add this marketplace from the repo:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
codex plugin marketplace add git@git.g4b.org:dirigence/reliquary.git
|
||||||
|
```
|
||||||
|
|
||||||
|
Then install the desired plugin:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
codex plugin add g4b_ai@reliquary
|
||||||
|
```
|
||||||
|
|
||||||
|
For local development from a checked-out repo, Codex also supports local marketplace sources:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
codex plugin marketplace add G:\dev\projects\reliquary
|
||||||
|
codex plugin add g4b_ai@reliquary
|
||||||
|
```
|
||||||
|
|
||||||
|
The local Codex help confirms the relevant command forms:
|
||||||
|
|
||||||
|
- `codex plugin marketplace add <SOURCE>`
|
||||||
|
- `codex plugin marketplace list`
|
||||||
|
- `codex plugin marketplace upgrade`
|
||||||
|
- `codex plugin add PLUGIN@MARKETPLACE`
|
||||||
|
- `codex plugin list`
|
||||||
|
|
||||||
|
## Using Workpad from Codex Projects
|
||||||
|
|
||||||
|
The `workpad` skill should remain inside the `g4b_ai` plugin:
|
||||||
|
|
||||||
|
```text
|
||||||
|
plugins/g4b_ai/skills/workpad/SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
For any Codex project that wants to use it, install and enable `g4b_ai@reliquary`, then add project-level `AGENTS.md` instructions similar to:
|
||||||
|
|
||||||
|
```md
|
||||||
|
# Project Instructions
|
||||||
|
|
||||||
|
Working documents live in `docs/workpad/`.
|
||||||
|
|
||||||
|
Use the `g4b_ai:workpad` skill for plans, research notes, specs, journals, reports, goals, and brainstorms.
|
||||||
|
```
|
||||||
|
|
||||||
|
This gives Codex both pieces it needs:
|
||||||
|
|
||||||
|
- the installed plugin supplies the actual `workpad` skill
|
||||||
|
- `AGENTS.md` supplies the project-specific workpad location and policy
|
||||||
|
|
||||||
|
For projects that do not already have `docs/workpad/`, the workpad skill can decide placement using its own rules. In this repository, `docs/workpad/` already exists and should remain the canonical location.
|
||||||
|
|
||||||
|
## Recommended Changes to Reliquary
|
||||||
|
|
||||||
|
1. Add `.agents/plugins/marketplace.json`.
|
||||||
|
2. Add `.codex-plugin/plugin.json` to each plugin directory.
|
||||||
|
3. Update the root `README.md` with separate Claude and Codex installation sections.
|
||||||
|
4. Add a short `AGENTS.md` at the repo root for Codex-specific repo instructions, mirroring the important parts of `CLAUDE.md`.
|
||||||
|
5. Add a validation note or script so marketplace updates keep Claude and Codex plugin lists in sync.
|
||||||
|
|
||||||
|
The Codex marketplace should include all plugins currently listed in `.claude-plugin/marketplace.json`: `g4b_ai`, `dioxus`, `project-uv`, and `gitea`.
|
||||||
|
|
||||||
|
## Compatibility Notes
|
||||||
|
|
||||||
|
Codex can currently consume the Claude marketplace layout in this environment, but that is an implementation detail from the user's perspective. The repo should publish Codex-native metadata so future Codex versions, Codex app UI flows, and third-party tooling can rely on the expected Codex structure.
|
||||||
|
|
||||||
|
Codex plugin cache behavior is version-sensitive. During local plugin development, Codex's own update guidance recommends changing the plugin version with a Codex cachebuster suffix, reinstalling the plugin, and starting a new thread so the new skills and tools are loaded.
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
- OpenAI Codex plugin creator skill: https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md
|
||||||
|
- OpenAI Codex plugin and marketplace JSON reference: https://raw.githubusercontent.com/openai/codex/main/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md
|
||||||
|
- OpenAI Codex local plugin update reference: https://raw.githubusercontent.com/openai/codex/main/codex-rs/skills/src/assets/samples/plugin-creator/references/installing-and-updating.md
|
||||||
|
- Local verification in this repo with Codex CLI 0.135.0-alpha.1.
|
||||||
Reference in New Issue
Block a user