kmp-versions

name	kmp-versions
category	create-project
description	Skill for resolving the correct, compatible set of versions for a Kotlin Multiplatform project. Instructs the AI to always fetch live version data from the official compatibility matrix instead of relying on its training data. Covers Kotlin/KGP, CMP, AGP, Gradle, and key library versions.
targets	["antigravity","claude","cursor","windsurf"]
sources	["https://kotlinlang.org/docs/multiplatform/multiplatform-compatibility-guide.html","https://kotlinlang.org/docs/gradle-configure-project.html","https://developer.android.com/kotlin/multiplatform/plugin","https://developer.android.com/build/releases/gradle-plugin","https://plugins.gradle.org/plugin/org.jetbrains.compose"]

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