Repository navigation
feat: add a skills-only Codex plugin manifest - #114
Merged
thomas-bartlett merged 3 commits intoAug 7, 2026
Merged
Conversation
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
approved these changes
Aug 7, 2026
thomas-bartlett
left a comment
Contributor
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refs #91. Adds
.codex-plugin/plugin.jsonso Codex can install and update theskills/codeguardskill 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.
.codex-plugin/plugin.jsonpointingskillsat./skills/validate_versions.pyandsync_plugin_metadata()so its version cannot drift frompyproject.tomldocs/codex-skill-plugin.md, a nav entry, and update the plugin-marketplace route indocs/install-paths.md(it previously said Claude Code only)Why skills-only
Two constraints shaped the boundary, and both are worth flagging for review:
skillsfield 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 thecodeguardskill andsources/skills/(security-review,memory-safe-migration) stays on the existing ZIP and rules routes.codeguard-revieweragent, 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
codeguard-security) and metadata, and declareslicense: CC-BY-4.0to matchLICENSE.md.interface.categoryout: the value set isn't documented, and everyinterfacefield is optional. Happy to add one if you know the accepted values.marketplace.json, and the existing.claude-plugin/marketplace.jsonalready declares this plugin at./, which is where the Codex manifest lives.Testing
Ran the same steps
build-ide-bundles.ymlruns:uv run python src/validate_unified_rules.py sources/— 108 passed, 0 faileduv 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-opuv run python src/convert_to_ide_formats.py— conversions successful,Synced plugin metadata to 1.4.0, and the manifest round-trips byte-identically throughset_codex_plugin_version()uv run mkdocs build --strict— cleanNot 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.