# Hugging Face

Recommend AXM extensions from a Hugging Face repo and target Hugging Face models from an extension.

The [two-way linking](/docs/package-ecosystems/overview) 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](https://github.com/package-url/purl-spec).

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.

## Recommend extensions from a repo

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

```yaml
# 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](https://github.com/package-url/purl-spec). The repo owner is the
namespace and the repo name is the name:

```jsonc
// 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](https://github.com/package-url/vers-spec)
`versionRange` with the `huggingface` scheme only when the extension depends on
a known revision range of the repo:

```jsonc
{
  "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](/docs/package-ecosystems/overview#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`](https://github.com/agentxm/polyglot-examples) fixtures
> before relying on it.