dirigence/reliquary

Fork 0

Files

T

g4borg 44927813c2 📝 Document Codex marketplace support

2026-05-30 15:19:18 +02:00

7.8 KiB

Raw Permalink Blame History

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:

[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:

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:

.agents/plugins/marketplace.json

Recommended shape:

{
  "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:

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:

{
  "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:

codex plugin marketplace add git@git.g4b.org:dirigence/reliquary.git

Then install the desired plugin:

codex plugin add g4b_ai@reliquary

For local development from a checked-out repo, Codex also supports local marketplace sources:

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:

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:

# 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

Add .agents/plugins/marketplace.json.
Add .codex-plugin/plugin.json to each plugin directory.
Update the root README.md with separate Claude and Codex installation sections.
Add a short AGENTS.md at the repo root for Codex-specific repo instructions, mirroring the important parts of CLAUDE.md.
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.

7.8 KiB Raw Permalink Blame History