npm

AXM reads npm extension metadata from a top-level agentExtensions field in package.json. This is the two-way linking model applied to the npm ecosystem.

Add an agentExtensions array to package.json. Each entry is an extension reference (@owner/<type>/<name>):

// package.json
{
  "name": "@agentxm/example-tinyflags",
  "version": "0.1.0",
  "agentExtensions": [{ "ref": "@examples/packs/javascript-npm-tinyflags" }],
}

Keep recommendations identity-only — no 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/javascript-npm-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}

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

// pack.json
{
  "packages": [{ "purl": "pkg:npm/%40agentxm/example-tinyflags" }],
}

npm scopes contain an @, which must be percent-encoded as %40 inside a purl. The scope separator stays a literal /:

{
  "packages": [{ "purl": "pkg:npm/%40agentxm/example-tinyflags" }],
}

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

{
  "packages": [
    {
      "purl": "pkg:npm/%40agentxm/example-tinyflags",
      "versionRange": "vers:npm/>=0.1.0|<1.0.0",
    },
  ],
}

When the npm 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 javascript-npm-lib and javascript-npm-app directories in polyglot-examples are the working fixtures for everything above. The library publishes a TinyFlags companion pack and recommends it from package.json; the pack and each skill declare the library's npm purl as a companion package — including the optional versionRange shape.