# Cargo

Recommend AXM extensions from a Cargo (Rust) crate and target Cargo crates from an extension.

AXM reads Rust extension metadata from `package.metadata.agentExtensions` in
`Cargo.toml`. This is the [two-way linking](/docs/package-ecosystems/overview)
model applied to the Cargo ecosystem.

## Recommend extensions from a crate

Add an `agentExtensions` array under `[package.metadata]` in `Cargo.toml`. Each
entry is an extension reference (`@owner/<type>/<name>`):

```toml
# Cargo.toml
[package]
name = "agentxm-example-tinyflags"
version = "0.1.0"

[package.metadata]
agentExtensions = [{ ref = "@examples/packs/rust-cargo-tinyflags" }]
```

Cargo ignores keys under `package.metadata`, so this table travels with your
published crate without affecting the build.

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

```toml
[package.metadata]
agentExtensions = [
  { ref = "@examples/packs/rust-cargo-tinyflags", versionRange = "^1.0.0" },
]
```

## Target Cargo crates from an extension

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

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

Use the crate's name from crates.io as the purl name.

### Version ranges

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

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

## Official status

When the Cargo crate recommends an extension through the AgentXM Registry
**and** that extension names the crate 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
[`rust-cargo-lib`](https://github.com/agentxm/polyglot-examples/tree/main/rust-cargo-lib)
and
[`rust-cargo-app`](https://github.com/agentxm/polyglot-examples/tree/main/rust-cargo-app)
directories in `polyglot-examples` are the working fixtures for everything
above. The crate publishes a TinyFlags companion pack and recommends it from
`package.metadata.agentExtensions` in `Cargo.toml`; the pack and each skill
declare the crate's Cargo purl as an identity-only companion package.