Agent Plugins Interoperability

CompozyOS can ingest the Agent Plugins 1.0.0 package layout as an extension. Detection is automatic: a root plugin.json selects the portable format when no native extension.toml or extension.json is present. This is an interoperability path, not a second lifecycle. Install, trust, enable, inspect, update, dev reload, secret binding, and removal continue to use the extension surfaces.

Package mapping

Agent Plugins package	CompozyOS extension
Root `plugin.json` identity	A synthesized resource-only manifest with `format: "agent-plugin"`.
Immediate child directories under `skills/`	Extension-kit skills. Malformed immediate entries are recorded as skipped diagnostics; deeper nesting is ignored.
`mcp.json` server with `type: "stdio"`	A packaged stdio MCP server.
`mcp.json` server with `type: "streamable-http"`	A packaged remote MCP server, normalized to the native `http` transport.
`PLUGIN_ROOT`	Absolute package root for managed and dev instances.
`PLUGIN_DATA`	Stable absolute data directory at `<COMPOZY_HOME>/extension-data/<name>/`.

Provider delivery

CompozyOS projects portable skills and MCP servers through the normal session resource path. The complete path is verified with managed Claude Code and Hermes sessions. The openclaw acp bridge currently rejects per-session MCP server configuration. When an enabled package requires hosted MCP, an OpenClaw-managed session fails before the provider launches instead of starting without its declared tools. OpenClaw's direct Agent Plugins support is separate from delivery through its ACP bridge.

CompozyOS does not fetch a schema while detecting a package. Schema 1.0.0 is the accepted contract. Client layouts use the adapter below. sse MCP servers are recorded as skipped, and sensitive package header values are never projected into runtime config. Bind remote credentials through the extension Vault flow instead.

Client plugin layouts

Without a native manifest, lookup selects the first existing manifest in this order: plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json. A selected invalid manifest fails; lookup does not fall through. Root plugin.json keeps the strict Agent Plugins schema. Client manifests may omit $schema; a declared unsupported Agent Plugins version still fails with the path of the file read.

Client metadata is adapted in memory, without rewriting the package. Skills are discovered under skills/ and at declared skills paths. mcpServers accepts a contained JSON file with a mcpServers object or an inline server map. Stdio and HTTP declarations become extension MCP resources. Commands, agents and hooks are not loaded and produce client_component_ignored diagnostics when declared or present.

The installed provenance records standard, claude-plugin, codex-plugin or cursor-plugin as layout. Layout grants no trust: existing consent, digest verification, credential isolation and lifecycle rules still apply. Paths must remain inside the package. Codex and Cursor currently use the same client grammar as Claude Code.

The vendored Open Design plugin contains one MCP server and no packaged skills; loop-engineering contains seven skills and no MCP declaration. The manifest description does not substitute for resources actually present in the package.

Native manifest precedence

When the package contains both a native manifest and plugin.json, the native manifest wins. Validate and install output includes a note about the unused portable manifest; status does not persist it as a runtime diagnostic. This gives one deterministic owner for identity, permissions, capabilities, and resources.

compozy extension validate ./acme-tools -o json
compozy extension install ./acme-tools --allow-unverified --yes
compozy extension status acme-tools -o json
compozy extension inventory acme-tools -o json

Validation reports the detected format, the resources CompozyOS would ingest, and ordered issues. Status and inventory retain the format and ingest diagnostics after installation, including when every portable component was skipped.

Credentials for remote MCP servers

Map a declared environment name to a remote request header without placing the credential in plugin.json, mcp.json, argv, logs, or API responses:

compozy extension secrets bind acme-tools \
  --env DEPLOY_API_TOKEN \
  --vault-ref vault:extensions/global/acme-tools/env/DEPLOY_API_TOKEN \
  --remote-header deployment-api:Authorization

The binding is scoped to that extension instance. Reads show mapping presence and names only, never the Vault reference or value.

Development

compozy extension dev <directory> --workspace <workspace> and extension reload validate Agent Plugins directly from their source directory, including the Claude, Codex and Cursor layouts. Keep that directory inside the selected workspace. The manifest name owns the instance identity, even when the directory has a different name; the source checksum identifies its development generation. Native CompozyOS extensions continue to build immutable bundles before linking.

Data and removal

PLUGIN_DATA survives updates and is deleted on compozy extension remove acme-tools. A failed deletion is quarantined before removal completes; if quarantine also fails, the operation aborts and the extension remains installed.

Marketplace metadata

A catalog entry may carry format: "agent-plugin" for display. Runtime detection remains authoritative, so stale or missing catalog metadata cannot change how an acquired package is parsed. Marketplace cards use the normal extension trust and install flow.

On this page