Pub

AXM reads Dart extension metadata from a top-level agentExtensions key in pubspec.yaml. This is the two-way linking model applied to the Pub ecosystem. The same convention covers plain Dart packages and Flutter packages.

Add an agentExtensions list to pubspec.yaml. Each entry is an extension reference (@owner/<type>/<name>):

# pubspec.yaml
name: agentxm_example_tinyflags
version: 0.1.0

agentExtensions:
  - { ref: "@examples/packs/dart-pub-tinyflags" }

Pub preserves unknown top-level keys, so the agentExtensions list travels with your published package.

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/dart-pub-tinyflags", versionRange: "^1.0.0" }

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

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

Use the package name as published to pub.dev as the purl name.

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

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

When the Pub 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 dart-pub-lib and dart-pub-app directories in polyglot-examples are the working fixtures for everything above. The package publishes a TinyFlags companion pack and recommends it from the agentExtensions key in pubspec.yaml; the pack and each skill declare the package's pkg:pub purl as an identity-only companion package.