Hex

AXM reads Hex extension metadata from an agent-extensions.json sidecar shipped at the package root. This is the two-way linking model applied to the Hex ecosystem.

Add an agent-extensions.json file at the package root with an agentExtensions array. Each entry is an extension reference (@owner/<type>/<name>):

// agent-extensions.json
{
  "$schema": "https://axm.sh/schemas/agent-extensions.schema.json",
  "agentExtensions": [{ "ref": "@examples/packs/elixir-hex-tinyflags" }],
}

Include the sidecar in the published tarball by listing it in the files key of your mix.exs package config, so consumers see it at deps/<package>/agent-extensions.json after mix deps.get:

# mix.exs
defp package do
  [
    files: ~w(lib mix.exs README.md agent-extensions.json)
  ]
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 package genuinely pairs with a bounded major line of the extension:

{
  "agentExtensions": [
    {
      "ref": "@examples/packs/elixir-hex-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a Hex purl:

// pack.json
{
  "packages": [{ "purl": "pkg:hex/agentxm_example_tinyflags" }],
}

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

{
  "packages": [
    {
      "purl": "pkg:hex/agentxm_example_tinyflags",
      "versionRange": "vers:hex/>=0.1.0|<1.0.0",
    },
  ],
}

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

The elixir-hex-lib and elixir-hex-app directories in polyglot-examples are the working fixtures for everything above. The package publishes a TinyFlags companion pack and recommends it from the agent-extensions.json sidecar (shipped via the files key in mix.exs); the pack and each skill declare the package's pkg:hex purl as an identity-only companion package.

AXM reads deps/<package>/agent-extensions.json as the primary source and falls back to parsing the recommendation out of hex_metadata.config when the sidecar is absent, so shipping agent-extensions.json via the files key remains the recommended path.