Plugin developer guide

Publish a Claude Code plugin to Codex, Cursor and Gemini CLI

By HOL · Reviewed by Michael Kantor on

Direct answer

Run hol-guard plugin check in the plugin repository to see what each runtime would reject, then hol-guard plugin package --runtimes codex,cursor,gemini-cli to write a ready-to-load folder for each runtime. Codex keeps your skills and MCP servers. Cursor and Gemini CLI get the MCP servers. Commands, agents and hooks stay Claude Code only, and the check lists what each runtime drops.

Who this is for

Maintainers of a Claude Code plugin who want the same plugin installable in Codex, Cursor and Gemini CLI.

Good fit

  • A Claude Code plugin that bundles MCP servers and skills
  • A marketplace repository that wants a Codex marketplace entry next to the Claude one
  • A team testing the same plugin across several agent runtimes

Not a fit

  • Plugins whose value is in hooks, slash commands or subagents, which only Claude Code loads
  • Rewriting prompts or skill instructions for a different model

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard 3.57 and newer. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it, then check that hol-guard --version reports 3.57 or newer.

    pipx install hol-guard
pipx upgrade hol-guard
hol-guard --version

  2. 2.Check the plugin

    The check reads .claude-plugin/plugin.json, .mcp.json, skills/, commands/, agents/ and hooks/hooks.json. It exits 0 when the plugin passes, 1 when it has errors such as a name that is not kebab-case or an MCP server without a command or url, and 2 when it could not run. Add --strict to fail on warnings too.

    hol-guard plugin check .

  3. 3.Package it for each runtime

    Packaging runs the check first and writes nothing when it fails. Each runtime gets its own folder under the output directory, plus hol.provenance.json with a SHA-256 digest of every file read and written.

    hol-guard plugin package . --runtimes codex,cursor,gemini-cli --out dist/hol-plugin

  4. 4.Make it installable

    hol-guard plugin links prints the install commands that already work and what is still missing, such as a .agents/plugins/marketplace.json entry so Codex can install the plugin from your repository.

    hol-guard plugin links .

  5. 5.Load each package

    Validate the output with each runtime before you publish it. These are the same checks the Plugin Kit runs weekly against pinned runtime releases.

    claude plugin validate dist/hol-plugin/claude-code
gemini extensions validate dist/hol-plugin/gemini-cli

  6. 6.Connect the repository on HOL

    Open the connect page with your repository to verify ownership and claim the listing. hol-guard plugin links prints the same link with your repository filled in. Installing the Guard GitHub App on the repository verifies its listings automatically.

    hol-guard plugin links .

What each runtime receives

Source or runtimeOutputCarriesDrops
Claude Code.claude-plugin/plugin.json, .mcp.jsonSkills, MCP servers, commands, agents, hooksNothing
Codex.codex-plugin/plugin.json, .mcp.jsonSkills, MCP serversCommands, agents, hooks
Gemini CLIgemini-extension.jsonMCP servers, context fileSkills, commands, agents, hooks
Cursor.cursor/mcp.jsonMCP serversSkills, commands, agents, hooks

Limitations

  • The Kit converts manifests and MCP config. It does not rewrite the behavior of a skill, command or hook.
  • MCP environment variables are written as references in each runtime's syntax. Values are never copied, so users still set them.
  • A listing or a passing check is not a safety guarantee.

Questions

Does the Kit upload my plugin anywhere?

No. It reads only the folder you name, never follows symlinks, runs no commands and makes no network calls.

Can I package for VS Code and OpenCode too?

Yes. Add vscode and opencode to --runtimes, or leave the flag out to write every supported runtime. Both receive the MCP servers.

How do I keep the packages in sync?

Run hol-guard plugin init to write a hol.json with your output folder and runtimes, then run hol-guard plugin package in CI. The same source always produces the same package.

Sources

Related guides

List it on HOL

Connect the repository to verify ownership and claim the listing. New plugins can be submitted for free.

Connect your plugin repository