Hugging Face

The two-way linking model applies to Hugging Face repositories just as it does to package ecosystems. A repo recommends through metadata in its model (or dataset) card, and an extension targets the repo through a Hugging Face purl.

A Hugging Face repository carries a README.md model card with a YAML front-matter block. AXM reads the recommendation from an agentExtensions key in that front-matter.

Add an agentExtensions list to the model-card front-matter. Each entry is an extension reference (@owner/<type>/<name>):

# README.md (model card front-matter)
---
license: apache-2.0
agentExtensions:
  - { ref: "@acme/packs/widget-kit" }
---

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 repo genuinely pairs with a bounded major line of the extension.

Target Hugging Face models from an extension

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a Hugging Face purl. The repo owner is the namespace and the repo name is the name:

// pack.json
{
  "packages": [{ "purl": "pkg:huggingface/acme/widget-model" }],
}

Use the owner/model identity as it appears on the Hub.

Version ranges

Default to identity-only. Add a VERS versionRange with the huggingface scheme only when the extension depends on a known revision range of the repo:

{
  "packages": [
    {
      "purl": "pkg:huggingface/acme/widget-model",
      "versionRange": "vers:huggingface/>=1.0.0|<2.0.0",
    },
  ],
}

Official status

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

The Hugging Face package-author metadata convention is still being finalized. The model-card front-matter location above is the natural carrier for repo metadata; the pkg:huggingface purl is the stable identity an extension uses to target a repo. Confirm the current shape against the polyglot-examples fixtures before relying on it.

Recommend extensions from a repo

Target Hugging Face models from an extension

Version ranges

Official status