CPAN

AXM reads Perl extension metadata from an x_agent_extensions field in the distribution's META.json. This is the two-way linking model applied to the CPAN ecosystem. The x_ prefix is the CPAN convention for custom metadata, so toolchains pass it through untouched.

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

// META.json
{
  "x_agent_extensions": [{ "ref": "@examples/packs/perl-cpan-tinyflags" }],
}

META.json is generated at build time (for example by Makefile.PL or Build.PL); add the x_agent_extensions field through your build tool's metadata hooks so it lands in the released distribution. Build tools propagate META.json into the installed MYMETA.json, which is where AXM reads the x_agent_extensions metadata after installation.

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

{
  "x_agent_extensions": [
    {
      "ref": "@examples/packs/perl-cpan-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a CPAN purl. Use the distribution name (with - separators) as the purl name:

// pack.json
{
  "packages": [{ "purl": "pkg:cpan/AgentXM-Examples-TinyFlags" }],
}

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

{
  "packages": [
    {
      "purl": "pkg:cpan/AgentXM-Examples-TinyFlags",
      "versionRange": "vers:cpan/>=0.1.0|<1.0.0",
    },
  ],
}

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

The perl-cpan-lib and perl-cpan-app directories in polyglot-examples are the working fixtures for everything above. The distribution publishes a TinyFlags companion pack and recommends it from the x_agent_extensions field in META.json; the pack and each skill declare the distribution's pkg:cpan purl as an identity-only companion package.