maven

name	maven
description	Always load this skill when a pom.xml file exists in the project, when creating or editing a pom.xml, or when setting up Maven project structure in a new project. It provides Maven-specific conventions for running tests, building, managing dependencies, and project structure.
version	0.1.0

Maven

Shared Maven conventions for all supported agent platforms.

First step — always: read your platform binding before running Maven, suggesting Maven commands, or giving sandbox advice.

Platform Bindings

Read your platform file before doing anything else.

• If maven_run is in your tool list: read skills/maven/pi.md (relative to the skill checkout)
• Otherwise: read skills/maven/claude.md (relative to the skill checkout)

Your platform file defines the concrete tools, fallback order, and sandbox/network rules. The rest of this file is shared Maven knowledge.

Managing POMs

Dependencies

When adding a new dependency:

• Use the latest stable release version — verify with version lookup (see below)
• Choose the appropriate scope (compile, provided, runtime, test) and keep them sorted by scope
• Prefer managed versions via <dependencyManagement> in the parent POM

Version properties typically follow the pattern <artifactId.version> or <groupId.version>, but use whatever is most concise and clear, e.g. assertj.version, cucumber.version, junit.version.

Version Lookup

Always fetch from Maven Central (or another authoritative repository) to verify the latest dependency or plugin version. Never trust version numbers from web search snippets, training data, or other secondary sources.

Use your platform binding's version-lookup tool first.

If that is not available, directly use the Maven repository metadata as a last resort. DO NOT USE search.maven.org — it's obsolete and returns outdated versions! Note: repo1.maven.org returns 403 for User-Agents that look like AI or crawlers. In sandboxed environments the sandbox may block curl — tell the user if that happens.

curl -s -A "Mozilla/5.0" \
  "https://repo1.maven.org/maven2/{groupId with . replaced by /}/{artifactId}/maven-metadata.xml"

These XML files contain the list of all versions. You'll have to strip pre-release versions, RC, beta, etc.

Exploring APIs of Dependencies

When you need to find out how a dependency's API works (method signatures, builder methods, interface contracts), use IDE tools (get_symbol_info, search_symbol) or the jdtls-lsp (goToDefinition, et al.). Both already index all dependencies and provide richer context including documentation and declarations. If neither are available, suggest to the user to install one or the other, including a short how-to.

Manual API Exploring Fallback

Only if the user denies more sophisticated tooling, fall back to working manually and read the source code of an artefact manually. Locate the sources JAR in the local Maven repository:

~/.m2/repository/{groupId with '.' replaced by '/'}/{artifactId}/{version}/{artifactId}-{version}-sources.jar

For example, org.example:my-lib:2.3.1 resolves to: ~/.m2/repository/org/example/my-lib/2.3.1/my-lib-2.3.1-sources.jar

To find the correct version:

• For direct dependencies: check the project's pom.xml <dependencies> section.
• For transitive dependencies: use mvn dependency:tree — resolution rules are complex.
• Always use the version matching the project's dependency tree, not whatever happens to be cached.

If the source JAR is not available, use your platform's preferred Maven execution path to run dependency:get -Dartifact=org.example:my-lib:2.3.1:jar:sources. Only if there is no source available in the Maven repo, use javap to decompile the jar file as a last resort.

Preview Features

If the project uses Java preview features, pass --enable-preview when running:

java --enable-preview -jar target/artifact.jar

This is typically configured in the Maven compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <enablePreview>true</enablePreview>
    </configuration>
</plugin>

Running Tests

Use your platform binding's Maven execution path first. It defines the concrete tool or CLI, how to pass profiles, and when raw mvn fallback is allowed.

Integration/System/Acceptance/E2E Tests

Tests that require a running service or a built jar file must use the Failsafe plugin, not Surefire: jars are not built in the test phase where Surefire is executing, and *IT.java files are not picked up by Surefire's default includes. Add the Failsafe plugin to the pom (including the execution goals; see below) and execute them on the verify lifecycle.

*ST.java and *AT.java don't match Failsafe's default includes either, so add them explicitly when required:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <configuration>
        <includes>
            <include>**/*IT.java</include>
            <include>**/*AT.java</include>
            <include>**/*ST.java</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Raw mvn Fallback

If you can't use better tooling and have to run tests via raw Maven, always quote -Dtest values containing # (method selectors) — unquoted # is parsed as a shell comment:

mvn test
mvn test -Dtest=VersionTest
mvn test -Dtest='MyTest#myMethod'

Building

Normally, clean is not necessary. Prefer incremental Maven builds/tests first. Reaching for clean by default only makes feedback slower and can hide the real problem.

But be ready to recognize stale build output:

• a test or runtime failure mentions a class that no longer has matching source code
• a class/resource was renamed, moved, or deleted, but old behaviour still shows up
• failures appear "impossible" compared to the current sources

In those cases, check whether the referenced class actually still exists in src/main or src/test. If it doesn't, a stale class file in target/ is a likely cause; then a clean build is justified.

Use your platform binding's Maven execution path first for packaging. If every agent-oriented option is unavailable, fall back to:

mvn package -DskipTests

JDT and Maven Output Isolation

If the jdtls plugin (based on Eclipse JDT, used by VS Code Java and Eclipse IDE) is active, always check that .settings/org.eclipse.jdt.core.prefs compiler compliance matches the POM's maven.compiler.source/maven.compiler.target. A mismatch (e.g. JDT on Java 17, POM on Java 21) causes JDT to flag valid API calls as errors.

JDT can also compile into the same target/classes directory as Maven, causing intermittent build failures:

• Symptom: java.lang.Error: Unresolved compilation problems at runtime, despite mvn compile succeeding ("Nothing to compile — all classes are up to date")
• Root cause: JDT overwrites Maven's class files. Maven sees the newer timestamp and skips recompilation. JDT's class files embed errors as runtime throws (unlike javac, which fails at compile time).
• Fix: Ensure .classpath output paths don't overlap with Maven's target/classes:

  <classpathentry kind="output" path="target/eclipse-classes"/>