Gradle Standards Skill | Agent Skills

Gradle Standards

Standards for Gradle configuration in Java projects, including version catalogs, dependency bundles, and multi-module setup.

When to use this skill

Setting up a new Gradle project
Adding or updating dependencies
Configuring multi-module builds
Troubleshooting dependency conflicts
Migrating to version catalogs
Cleaning up unused dependencies
Optimizing build performance
When asked for "gradle dependencies cleanup"

Skill Contents

Available Resources

📚 references/ - Detailed documentation

Quick Start

1. Version Centralization (Required)

All versions MUST be centralized in gradle/libs.versions.toml:

[versions]
spring-boot = "3.5.9"
grpc = "1.78.0"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" }
spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator", version.ref = "spring-boot" }

2. Use in build.gradle

dependencies {
    // ✅ CORRECT: Use version catalog with explicit dependencies
    implementation libs.spring.boot.starter.web
    implementation libs.spring.boot.starter.actuator

    // ❌ NEVER: Hardcode versions
    // implementation "org.springframework.boot:spring-boot-starter-web:3.5.9"
}

Key Principles

| Principle | Description | |-----------|-------------| | Centralize Versions | All versions in libs.versions.toml, never inline | | Explicit Dependencies | Declare each dependency explicitly for clarity | | Use Native Locking | Use Gradle's native dependency locking (Gradle 9+ recommended) | | Never Downgrade | Don't replace existing versions with older ones | | Use platform() for BOMs | Import BOMs via platform(), never enforcedPlatform() or mavenBom directives | | Catalog First | All versions should come from the version catalog; use resolutionStrategy.force only as a last resort for security | | Lock Dependencies | Generate gradle.lockfile for ALL submodules (use custom resolveAndLockAll task with --write-locks; see native-dependency-locking.md for task definition) |

Version Conflicts

All projects should preferably use the versions defined in the version catalog. When the resolved version doesn't match the catalog for some reason, prefer fixing the root cause:

First: Define the correct version in the version catalog and declare the dependency explicitly
Second: Use platform() to import a BOM that manages the version (e.g., Spring Boot dependencies)
Last resort: Use resolutionStrategy.force only for security-critical overrides where the above approaches don't work

// AVOID unless absolutely necessary for security
configurations.configureEach {
    resolutionStrategy {
        // Only for security-critical overrides as a last resort
        force libs.commons.compress  // CVE fix not yet in BOM
    }
}

References

| Reference | Description | |-----------|-------------| | references/version-catalogs.md | Complete version catalog guide | | references/multi-module.md | Multi-module project setup | | references/native-dependency-locking.md | Gradle native locking (Gradle 9+ recommended) | | references/cleanup-workflow.md | Dependency cleanup process | | references/unused-detection.md | Finding unused dependencies | | references/optimization.md | Build optimization techniques | | references/troubleshooting.md | Common issues and solutions |

Related Rules

java-gradle-best-practices - Full Gradle configuration reference
java-versions-and-dependencies - Version management policies

Dependency Resolution Stack

┌─────────────────────────────────────────────────────────────────────┐
│  1. VERSION CATALOG (libs.versions.toml)                            │
│     Single source of truth for declared versions                    │
├─────────────────────────────────────────────────────────────────────┤
│  2. RESOLUTION STRATEGY (build.gradle)                              │
│     Use Gradle's native resolutionStrategy for:                     │
│     - force() for security fixes                                    │
│     - eachDependency for group alignment                            │
│     - dependencySubstitution for module replacement                 │
├─────────────────────────────────────────────────────────────────────┤
│  3. LOCK FILE (gradle.lockfile)                                     │
│     Native Gradle locking (Gradle 9+ recommended)                   │
│     Captures EXACT resolved versions                                │
│                                                                     │
│  ⚠️  CRITICAL: Multi-module projects need lockfiles for ALL modules │
│     Use: ./gradlew resolveAndLockAll --write-locks                  │
│     NOT: ./gradlew dependencies --write-locks (root only!)          │
└─────────────────────────────────────────────────────────────────────┘

Lock File:

Native locking - Built-in, no plugins, recommended for Gradle 9+

Multi-Module Lockfile Generation:

# ✅ CORRECT: Generates lockfiles for ALL submodules
./gradlew resolveAndLockAll --write-locks --refresh-dependencies --no-daemon --no-scan

# ❌ WRONG: Only generates for ROOT project
./gradlew dependencies --write-locks

# Verify coverage (lockfiles should ≈ build.gradle files)
find . -name "gradle.lockfile" | wc -l
find . -name "build.gradle" | wc -l

Related Skills

| Skill | Purpose | |-------|---------| | dependency-management | Version catalogs and BOMs | | dependabot-security | Security vulnerability fixes | | java-coverage | JaCoCo configuration in Gradle | | java-testing | Test configuration with Spock |

Agent Skills: Gradle Standards

Install this agent skill to your local

Skill Files