Adding a plugin
A plugin purisev maintains lives in its own repository, such as purisev/openviking-wiki, or as a directory of purisev/agent-skills, which suits plugins made only of skills. purisev/agent-plugins holds the two catalogs, the installer and this site. Plugins from other authors follow Third-party plugins.
- Give the plugin repository a
.claude-plugin/plugin.jsonwith anameand aversion, and check it withclaude plugin validate <checkout>/.claude-plugin/plugin.json. For Codex it also needs a.codex-plugin/plugin.json. - Add an entry with the same
nameto both catalogs:.claude-plugin/marketplace.json— aurlsource with the https clone URL, or agit-subdirsource for a directory of purisev/agent-skills, with noref, so it follows the default branch. Not agithubsource: Claude Code clones that over SSH and fails without an SSH key for GitHub;.agents/plugins/marketplace.json— the same source with"ref": "main", and apolicy. Codex lists nothing from the first file.
- A plugin that needs another plugin from this catalog lists it under
dependenciesin its.claude-plugin/plugin.json. A bare name resolves inside this marketplace, so Claude Code installs it automatically. - Add the plugin to
ALL_PLUGINSindocs/install.shand to$AllPluginsand the-PluginValidateSetindocs/install.ps1, and give it a section indocs/plugins.md. - Run the checks and open a pull request.
Do not give a plugin repository a marketplace.json of its own. The same plugin reachable through two
marketplaces can be enabled twice, and its hooks then run twice.
Claude Code tells plugin versions apart by version in plugin.json, so raise it with every release.
Third-party plugins
A plugin from another author is listed from its own repository and pinned to one commit, so an install never follows someone else’s branch:
- Claude Code: a
urlorgit-subdirsource withref(the release tag, or the branch when there are no releases) andsha(the full commit). A source without.claude-plugin/plugin.jsonneeds no wrapper: the catalog entry is then its manifest, so give itdescription,version,author,licenseandskills, as theplaywrightentry does. - Codex: the same repository,
refandsha, when the source has a manifest Codex reads and its skills underskills/. Otherwise Codex installs the plugin empty, without an error. Such a plugin gets a Codex-only copy in purisev/agent-skills, whose README describes the layout, and joinsCODEX_WRAPPERSinmarketplace.test.mjs.
An install that succeeds does not prove that Codex found the skills. codex debug prompt-input hi
prints the prompt Codex would send, and its skills section lists every skill it loaded.
To move a third-party plugin to a new release, change ref and sha in both catalogs, and for a
wrapper follow the update steps in the purisev/agent-skills README.
Hooks shared by both hosts use ${CLAUDE_PLUGIN_ROOT} in their commands: Claude Code expands only that
token, and Codex provides it next to its own ${PLUGIN_ROOT}.
Checks
node --test
claude plugin validate .
codex plugin marketplace add . && codex plugin list
mdbook build
node --test needs no network. It guards both catalogs and that they agree, and runs both installers
against stand-ins for claude, codex, git and node, so nothing is installed. The install.ps1
cases are skipped where pwsh is missing.
The marketplace name purisev is part of every installed plugin’s id and of users’ settings. Renaming
it would orphan those installs.