Plugin developer guide

Package a plugin for the Agent Plugins 1.0 specification

By HOL · Reviewed by Michael Kantor on

Direct answer

An Agent Plugins 1.0 package is a folder with a root plugin.json that declares the 1.0 $schema and a name, plus optional skills/ and mcp.json. Run hol-guard plugin convert --to agent-plugins to write that layout from a Claude Code, Codex or Gemini CLI plugin, then hol-guard plugin check --spec agent-plugins-1.0. Each finding names the spec section and whether a client rejects the whole plugin or only one component.

Who this is for

Plugin authors who want one portable package that any Agent Plugins client can load.

Good fit

  • A plugin already shipped for Claude Code or Codex
  • Skills and MCP servers kept in one portable folder
  • A CI check that the package still conforms

Not a fit

  • Client-specific install, update or UI behavior, which the specification leaves to each client

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it so the Kit commands below are available.

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

  2. 2.Convert to the Agent Plugins layout

    Conversion writes plugin.json and mcp.json in the 1.0 layout and copies skills into skills/<name>/. Each MCP server gets its type, and ${CLAUDE_PLUGIN_ROOT} and similar placeholders become ${PLUGIN_ROOT}. The package is checked against the specification after it is written.

    hol-guard plugin convert . --to agent-plugins --out dist/agent-plugins

  3. 3.Check against the specification

    The check exits 0 when the folder conforms and 1 when it does not. Each finding names its section and what a client does about it, such as rejecting the whole plugin or skipping one server.

    hol-guard plugin check dist/agent-plugins --spec agent-plugins-1.0

  4. 4.Keep files inside the plugin root

    Files the package supplies must resolve inside the plugin root. Plugin-relative paths start with ./, and symlinks must not escape the package. Only ${PLUGIN_ROOT} and ${PLUGIN_DATA} are expanded.

  5. 5.Add the install block to your README

    hol-guard plugin links --block prints a README block between hol-install-block markers: one hol-guard plugin install command, how to get HOL Guard, and each runtime's own install commands for the runtimes the repository already supports. Paste it into the README; HOL finds it on its next scan and shows the install count on your listing once enough installs are reported.

    hol-guard plugin links . --block

  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 the repository filled in.

    hol-guard plugin links .

Limitations

  • How a client installs, updates and enables a plugin is outside the specification.
  • Servers that need runtime-specific fields the specification cannot express are reported, not silently dropped.
  • A listing, a passing check or a marketplace review is not a safety guarantee. HOL shows its scan evidence on the listing so users can judge for themselves.

Questions

Does Codex read Agent Plugins manifests?

The Codex plugin manifest in .codex-plugin/plugin.json uses the Agent Plugins 1.0 $schema in the Codex docs.

Who maintains the specification?

Its Technical Steering Committee includes core maintainers from Amazon, Cursor, Microsoft, OpenAI and Vercel.

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