RubyGems

AXM reads Ruby extension metadata from a JSON-stringified declaration stored under spec.metadata["agent_extensions"] in the gemspec. This is the two-way linking model applied to the RubyGems ecosystem.

Set metadata["agent_extensions"] in your .gemspec to a JSON array of extension declarations. RubyGems metadata values must be strings, so the array is JSON-encoded into a single string. Each entry is an extension reference (@owner/<type>/<name>):

# agentxm-example-tinyflags.gemspec
Gem::Specification.new do |spec|
  spec.name = "agentxm-example-tinyflags"
  spec.metadata = {
    "agent_extensions" => "[{\"ref\":\"@examples/packs/ruby-rubygems-tinyflags\"}]"
  }
end

Keep recommendations identity-only — omit versionRange. AXM resolves the reference to the newest matching extension version and pins it in the user's axm.lock. Prefer recommending a single pack so you keep one stable reference while its contents evolve.

Add a semver versionRange only when your gem genuinely pairs with a bounded major line of the extension. The decoded JSON then carries the range:

spec.metadata = {
  "agent_extensions" =>
    "[{\"ref\":\"@examples/packs/ruby-rubygems-tinyflags\",\"versionRange\":\"^1.0.0\"}]"
}

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a RubyGems purl. The RubyGems purl type is gem:

// pack.json
{
  "packages": [{ "purl": "pkg:gem/agentxm-example-tinyflags" }],
}

Default to identity-only. Add a VERS versionRange with the gem scheme only when the extension depends on gem APIs introduced or removed in a known range:

{
  "packages": [
    {
      "purl": "pkg:gem/agentxm-example-tinyflags",
      "versionRange": "vers:gem/>=0.1.0|<1.0.0",
    },
  ],
}

When the gem recommends an extension through the AgentXM Registry and that extension names the gem as a companion via its purl, AXM derives official status for the pair — no extra flag. See Official extensions.

The ruby-rubygems-lib and ruby-rubygems-app directories in polyglot-examples are the working fixtures for everything above. The gem publishes a TinyFlags companion pack and recommends it via spec.metadata["agent_extensions"]; the pack and each skill declare the gem's pkg:gem purl as an identity-only companion package.