Kmp Versions

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:

| Library | Check URL | |---|---| | kotlinx-coroutines | https://github.com/Kotlin/kotlinx.coroutines/releases | | kotlinx-serialization | https://github.com/Kotlin/kotlinx.serialization/releases | | androidx.lifecycle | https://developer.android.com/jetpack/androidx/releases/lifecycle | | androidx.navigation | https://developer.android.com/jetpack/androidx/releases/navigation | | Koin | https://github.com/InsertKoinIO/koin/releases | | Coil 3 | https://github.com/coil-kt/coil/releases |

---

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:

| Kotlin | AGP min | AGP max | |---|---|---| | 2.4.0 | 8.5.2 | 9.1.0 | | 2.3.20–2.3.21 | 8.2.2 | 9.0.0 | | 2.3.0 | 8.2.2 | 8.13.0 | | 2.2.20–2.2.21 | 7.3.1 | 8.11.1 | | 2.1.20–2.1.21 | 7.3.1 | 8.7.2 |

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

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

| Kotlin | Gradle min | Gradle max | |---|---|---| | 2.4.0 | 7.6.3 | 9.5.0 | | 2.3.20–2.3.21 | 7.6.3 | 9.3.0 | | 2.2.20–2.2.21 | 7.6.3 | 8.14 | | 2.1.20–2.1.21 | 7.6.3 | 8.12.1 |

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)

| From → To | Breaking Change | Action | |---|---|---| | Any → CMP 1.8.2 | material-icons-core no longer transitive | Add explicitly to toml | | Any → CMP 1.10 | compose.* plugin accessors deprecated | Use libs.* references | | Any → Kotlin 2.3.0 | androidTarget {} block deprecated → warn | Rename to android {} (use new plugin) | | Any → Kotlin 2.2.0 | android {} DSL removed from KMP plugin | Must use com.android.kotlin.multiplatform.library | | Any → AGP 9.0 | com.android.library incompatible with KMP plugin | Restructure project; separate androidApp module | | Any → Kotlin 2.1.20 | withJava() deprecated | Remove it; Java source sets created automatically | | Any → Kotlin 2.2.0 | ios(), watchos(), tvos() shortcuts removed | Use explicit targets: iosArm64(), iosSimulatorArm64() |

---

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

| Resource | URL | |---|---| | KMP Compatibility Matrix (Kotlin / Gradle / AGP / Xcode) | https://kotlinlang.org/docs/multiplatform/multiplatform-compatibility-guide.html | | KGP + Gradle + AGP table | https://kotlinlang.org/docs/gradle-configure-project.html | | CMP Releases & What's New | https://www.jetbrains.com/help/kotlin-multiplatform-dev/whats-new-compose.html | | AGP Release Notes | https://developer.android.com/build/releases/gradle-plugin | | Gradle Releases | https://gradle.org/releases/ | | KMP Wizard (generates a valid project) | https://kmp.jetbrains.com/ | | Coroutines | https://github.com/Kotlin/kotlinx.coroutines/releases | | Serialization | https://github.com/Kotlin/kotlinx.serialization/releases | | Lifecycle | https://developer.android.com/jetpack/androidx/releases/lifecycle | | Koin | https://github.com/InsertKoinIO/koin/releases | | Navigation Compose | https://developer.android.com/jetpack/androidx/releases/navigation | | Coil 3 | https://github.com/coil-kt/coil/releases |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: iammohdzaki
• Source: iammohdzaki/kmp-skills
• License: MIT

Install and usage instructions live in the source repository linked above.