# CPAN

Recommend AXM extensions from a CPAN (Perl) distribution and target CPAN packages from an extension.

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

## Recommend extensions from a distribution

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

```jsonc
// 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:

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

## Target CPAN packages from an extension

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

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

### Version ranges

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

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

## Official status

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](/docs/package-ecosystems/overview#official-extensions).

## Reference fixture

The
[`perl-cpan-lib`](https://github.com/agentxm/polyglot-examples/tree/main/perl-cpan-lib)
and
[`perl-cpan-app`](https://github.com/agentxm/polyglot-examples/tree/main/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.