KMP Version Compatibility Skill

CRITICAL — AI VERSIONING WARNING

>

AI models have a training data cutoff and will hallucinate stale or incompatible version numbers for KMP projects if asked from memory. This skill exists to override that behavior.

>

You MUST follow the protocol below every time versions are needed for a KMP project. Never generate a libs.versions.toml from memory alone.

Protocol: How to Resolve Versions

When setting up or updating a KMP project, always fetch live version data using this exact sequence. Do not skip steps.

Step 1 — Fetch the official KGP compatibility matrix

Read this page to get the current Kotlin / Gradle / AGP compatibility table:

https://kotlinlang.org/docs/multiplatform/multiplatform-compatibility-guide.html

Extract the latest stable Kotlin version and its maximum supported AGP and Gradle versions.

Step 2 — Confirm Compose Multiplatform version

Read the CMP releases page to find the latest stable CMP version compatible with the Kotlin version from Step 1:

https://www.jetbrains.com/help/kotlin-multiplatform-dev/whats-new-compose.html

Or check the plugin portal for the latest published version:

https://plugins.gradle.org/plugin/org.jetbrains.compose

Step 3 — Confirm AGP version

Check the Android Gradle Plugin release notes for the latest stable version:

https://developer.android.com/build/releases/gradle-plugin

Cross-check that the chosen AGP version falls within the KGP compatibility range from Step 1.

Step 4 — Confirm Gradle wrapper version

Use the Gradle releases page to find the latest stable Gradle version within the KGP range:

https://gradle.org/releases/

Step 5 — Confirm library versions

Check Maven Central or the official library repos for the latest stable versions:

Compatibility Rules (always apply)

These rules are structural — they do not change with versions.

Rule 1: Kotlin version = KGP version = composeCompiler plugin version

The Kotlin Gradle Plugin (KGP), the Compose compiler plugin, and the Kotlin stdlib all use the same version number. They are always in sync.

kotlin = "2.x.x"  # One version for: KGP, composeCompiler plugin, kotlin-test

Rule 2: AGP must be in the range for your Kotlin version

From the official matrix at kotlinlang.org/docs/gradle-configure-project.html:

Always verify this table from the live URL — versions update regularly.

Rule 3: Gradle wrapper must be in the range for your Kotlin version

Rule 4: AGP ≥ 9.0 requires project restructure (see kmp-project-structure skill)

With AGP 9.0+, com.android.application and com.android.library cannot coexist with org.jetbrains.kotlin.multiplatform in the same module. The project must use the new com.android.kotlin.multiplatform.library plugin in the shared module and a separate androidApp module for the app entry point.

Rule 5: Compose Multiplatform version drives Compose library versions

All org.jetbrains.compose.* library versions must match the CMP plugin version exactly. Never mix CMP library versions with a different CMP plugin version.

composeMultiplatform = "1.x.x"  # Plugin AND all org.jetbrains.compose.* libraries use this

compose-material3          = { module = "org.jetbrains.compose.material3:material3",            version.ref = "composeMultiplatform" }
compose-runtime            = { module = "org.jetbrains.compose.runtime:runtime",                version.ref = "composeMultiplatform" }
compose-ui                 = { module = "org.jetbrains.compose.ui:ui",                          version.ref = "composeMultiplatform" }
compose-foundation         = { module = "org.jetbrains.compose.foundation:foundation",          version.ref = "composeMultiplatform" }
compose-material-icons-core = { module = "org.jetbrains.compose.material:material-icons-core", version.ref = "composeMultiplatform" }

Rule 6: Never use deprecated compose.* plugin accessor shorthands

Deprecated since CMP 1.10.0-beta01. Always use explicit libs.* references:

// ❌ Deprecated
implementation(compose.material3)
implementation(compose.ui)

// ✅ Correct
implementation(libs.compose.material3)
implementation(libs.compose.ui)

Rule 7: material-icons-core is NOT transitive since CMP 1.8.2

Always declare it explicitly if you use any Icons.*:

compose-material-icons-core = { module = "org.jetbrains.compose.material:material-icons-core", version.ref = "composeMultiplatform" }

Version Catalog Template

⚠️ Fill in versions only after completing the 5-step protocol above. Do not use the placeholder version numbers in this template as real versions.

[versions]
# ── Fetch from: kotlinlang.org/docs/multiplatform/multiplatform-compatibility-guide.html
kotlin               = "FETCH_FROM_OFFICIAL_SOURCE"

# ── Fetch from: developer.android.com/build/releases/gradle-plugin
# ── Must be in the AGP range for your Kotlin version
agp                  = "FETCH_FROM_OFFICIAL_SOURCE"

# ── Fetch from: plugins.gradle.org/plugin/org.jetbrains.compose
# ── Must be compatible with your Kotlin version
composeMultiplatform = "FETCH_FROM_OFFICIAL_SOURCE"

# ── Standard libraries — fetch latest stable from GitHub releases
coroutines           = "FETCH_FROM_OFFICIAL_SOURCE"
serialization        = "FETCH_FROM_OFFICIAL_SOURCE"

# ── Fetch from: developer.android.com/jetpack/androidx/releases/lifecycle
lifecycle            = "FETCH_FROM_OFFICIAL_SOURCE"

[libraries]
# Compose Multiplatform — explicit (compose.* accessors deprecated in CMP 1.10)
compose-runtime             = { module = "org.jetbrains.compose.runtime:runtime",                version.ref = "composeMultiplatform" }
compose-foundation          = { module = "org.jetbrains.compose.foundation:foundation",           version.ref = "composeMultiplatform" }
compose-ui                  = { module = "org.jetbrains.compose.ui:ui",                           version.ref = "composeMultiplatform" }
compose-material3           = { module = "org.jetbrains.compose.material3:material3",             version.ref = "composeMultiplatform" }
compose-material-icons-core = { module = "org.jetbrains.compose.material:material-icons-core",   version.ref = "composeMultiplatform" }
compose-ui-tooling-preview  = { module = "org.jetbrains.compose.ui:ui-tooling-preview",          version.ref = "composeMultiplatform" }

# Kotlin standard libraries
kotlinx-coroutines-core     = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core",        version.ref = "coroutines" }
kotlinx-serialization-json  = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json",     version.ref = "serialization" }
lifecycle-viewmodel         = { module = "androidx.lifecycle:lifecycle-viewmodel",               version.ref = "lifecycle" }
kotlin-test                 = { module = "org.jetbrains.kotlin:kotlin-test",                     version.ref = "kotlin" }

[plugins]
kotlinMultiplatform  = { id = "org.jetbrains.kotlin.multiplatform",       version.ref = "kotlin" }
androidApplication   = { id = "com.android.application",                  version.ref = "agp" }
composeMultiplatform = { id = "org.jetbrains.compose",                    version.ref = "composeMultiplatform" }
composeCompiler      = { id = "org.jetbrains.kotlin.plugin.compose",      version.ref = "kotlin" }
kotlinSerialization  = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

# Required for AGP 9.0+ projects (new project structure — see kmp-project-structure skill)
# androidKmpLibrary = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }

Gradle Wrapper

Set distributionUrl in gradle/wrapper/gradle-wrapper.properties to the latest stable Gradle version within the range for your Kotlin version:

distributionUrl=https\://services.gradle.org/distributions/gradle-X.X.X-bin.zip

Fetch the latest stable from: https://gradle.org/releases/

Known Breaking Changes (version-gated)

Official Sources (always use these — do not rely on AI memory)