Skip to content

feat: add a skills-only Codex plugin manifest - #114

Merged
thomas-bartlett merged 3 commits into
cosai-oasis:mainfrom
vismaytiwari:agent/codex-plugin-manifest
Aug 7, 2026
Merged

thomas-bartlett merged 3 commits into
cosai-oasis:mainfrom
vismaytiwari:agent/codex-plugin-manifest

Conversation

@vismaytiwari

Copy link
Copy Markdown
Contributor

Summary

Refs #91. Adds .codex-plugin/plugin.json so Codex can install and update the skills/codeguard skill through its marketplace commands, alongside the existing Claude Code manifest.

Recording the recommendation the issue asks for: build, scoped to skills only for a first version.

  • add .codex-plugin/plugin.json pointing skills at ./skills/
  • register the new manifest in validate_versions.py and sync_plugin_metadata() so its version cannot drift from pyproject.toml
  • add docs/codex-skill-plugin.md, a nav entry, and update the plugin-marketplace route in docs/install-paths.md (it previously said Claude Code only)

Why skills-only

Two constraints shaped the boundary, and both are worth flagging for review:

  • Codex's skills field is documented as a single path, where the Claude Code manifest accepts a list of two roots. A 1:1 port isn't possible, so ./skills/ resolves to the codeguard skill and sources/skills/ (security-review, memory-safe-migration) stays on the existing ZIP and rules routes.
  • The codeguard-reviewer agent, hooks, and MCP servers are separate distribution decisions. Leaving them out keeps this reviewable on its own, and each is additive to the manifest later without changing how the skill installs.

The docs say so explicitly, so nobody reads the plugin as a replacement for the other routes.

Notes for reviewers

  • The manifest reuses the existing plugin identity (codeguard-security) and metadata, and declares license: CC-BY-4.0 to match LICENSE.md.
  • I left interface.category out: the value set isn't documented, and every interface field is optional. Happy to add one if you know the accepted values.
  • No new marketplace file is needed. Per OpenAI's plugin docs a plugin repository doesn't require its own marketplace.json, and the existing .claude-plugin/marketplace.json already declares this plugin at ./, which is where the Codex manifest lives.

Testing

Ran the same steps build-ide-bundles.yml runs:

  • uv run python src/validate_unified_rules.py sources/ — 108 passed, 0 failed
  • uv run python src/validate_versions.py 1.4.0 — all five versions match, now including .codex-plugin/plugin.json; also confirmed it fails when given a mismatched version, so the new check isn't a no-op
  • uv run python src/convert_to_ide_formats.py — conversions successful, Synced plugin metadata to 1.4.0, and the manifest round-trips byte-identically through set_codex_plugin_version()
  • uv run mkdocs build --strict — clean

Not verified locally: I don't have the Codex CLI here, so the marketplace commands in the docs follow OpenAI's plugin documentation rather than an end-to-end install I ran myself. Worth a sanity check by someone with Codex to hand before release.

Codex reads a plugin manifest from .codex-plugin/plugin.json, so add one next to
the existing Claude Code manifest. It packages the skills/codeguard skill,
letting Codex users install and update it with the marketplace commands instead
of copying files.

The manifest is deliberately skills-only. Codex's skills field takes a single
path rather than the list the Claude Code manifest uses, so ./skills/ resolves to
the codeguard skill and sources/skills/ stays on the existing ZIP and rules
routes. Agents, hooks, and MCP servers are separate distribution decisions and
can be added later without changing how the skill installs.

Wire the new file into validate_versions.py and sync_plugin_metadata() so a
release cannot ship with its version left behind, and document the install,
verification, and scope alongside the Claude Code guide.

Refs cosai-oasis#91
The install section stopped at registering the marketplace, which does not
install anything. Add the `codex plugin add` step, note that repository-root
marketplace sources need Codex CLI 0.142.0 or newer, and separate verifying an
installed plugin from the maintainer metadata checks.

Also drop the "zero local files / auto-updates" framing for this route:
`marketplace upgrade` refreshes a configured snapshot on request rather than
updating automatically. Mention Codex alongside Claude Code in the install-path
comparison, personas list, and flowchart legend.

@thomas-bartlett thomas-bartlett left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for making this change! I added a few small documentation simplifications and wording clarifications, along with automated version validation for the Codex manifest. The implementation looks good and all checks are passing. Approved.

@thomas-bartlett
thomas-bartlett merged commit 7e19e20 into cosai-oasis:main Aug 7, 2026
2 checks passed
@thomas-bartlett thomas-bartlett mentioned this pull request Sep 29, 2026
6 of 7 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants