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:

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)