Maven

AXM reads JVM extension metadata from an agent-extensions.json file under src/main/resources/META-INF/, which is packaged into the published JAR. This is the two-way linking model applied to the Maven ecosystem. The same convention covers Java, Kotlin, and Scala artifacts published to Maven repositories.

Add src/main/resources/META-INF/agent-extensions.json with an agentExtensions array. Each entry is an extension reference (@owner/<type>/<name>):

// src/main/resources/META-INF/agent-extensions.json
{
  "$schema": "https://axm.sh/schemas/agent-extensions.schema.json",
  "agentExtensions": [{ "ref": "@examples/packs/java-maven-tinyflags" }],
}

Placing the file under META-INF/ ensures it ships inside the JAR alongside your classes without any extra build configuration.

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/java-maven-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a Maven purl. Maven purls put the group id in the namespace and the artifact id in the name, separated by /:

// pack.json
{
  "packages": [{ "purl": "pkg:maven/ai.agentxm.examples/tinyflags-java" }],
}

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

{
  "packages": [
    {
      "purl": "pkg:maven/ai.agentxm.examples/tinyflags-java",
      "versionRange": "vers:maven/>=0.1.0|<1.0.0",
    },
  ],
}

When the Maven 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 java-maven-lib and java-maven-app directories in polyglot-examples are the working fixtures for everything above; kotlin-maven-* and scala-maven-* pairs follow the same shape. The package publishes a TinyFlags companion pack and recommends it from META-INF/agent-extensions.json; the pack and each skill declare the package's Maven purl as an identity-only companion package.