# RubyGems

Recommend AXM extensions from a RubyGems gem and target RubyGems packages from an extension.

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](/docs/package-ecosystems/overview) model applied to the
RubyGems ecosystem.

## Recommend extensions from a gem

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>`):

```ruby
# 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:

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

## Target RubyGems packages from an extension

On the extension manifest (`skill.json`, `pack.json`, `subagent.json`, …), add a
`packages` array with a RubyGems
[purl](https://github.com/package-url/purl-spec). The RubyGems purl type is
`gem`:

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

### Version ranges

Default to identity-only. Add a [VERS](https://github.com/package-url/vers-spec)
`versionRange` with the `gem` scheme only when the extension depends on gem APIs
introduced or removed in a known range:

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

## Official status

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](/docs/package-ecosystems/overview#official-extensions).

## Reference fixture

The
[`ruby-rubygems-lib`](https://github.com/agentxm/polyglot-examples/tree/main/ruby-rubygems-lib)
and
[`ruby-rubygems-app`](https://github.com/agentxm/polyglot-examples/tree/main/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.