skilld
All skills
kotlin avatar

/kotlin-tooling-agp9-migration

@43f4771 official
by kotlinkotlin/kotlin-agent-skills1.1k stars
42

Migrates Kotlin Multiplatform (KMP) projects to Android Gradle Plugin 9.0+. Handles plugin replacement (com.android.kotlin.multiplatform.library), module splitting, DSL migration, and the new default project structure. Use when upgrading AGP, when build fails due to KMP+AGP incompatibility, or when the user mentions AGP 9.0, android multiplatform plugin, KMP migration, or com.android.kotlin.multiplatform.library.

Ask your Agent

Use this Skill: https://skilld.dev/gh/kotlin/kotlin-agent-skills/kotlin-tooling-agp9-migration

This session only. Nothing lands on disk.

referencesVERSION-MATRIX.md

≈2.6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Version Compatibility Matrix for KMP AGP 9.0 Migration

Compatibility Table

Component Minimum Recommended Notes
AGP 9.0.0 9.0.1+ 9.0.0 is the initial release; 9.0.1+ includes early bug fixes
Gradle 9.1.0 9.1.0+ AGP 9.0 requires Gradle 9.1+; earlier Gradle versions will not work
JDK 17 17+ AGP 9.0 requires JDK 17 minimum
SDK Build Tools 36.0.0 36.0.0 Required by AGP 9.0
KGP (Kotlin Gradle Plugin) 2.0.0 2.3.0+ 2.0.0 is minimum for KMP library plugin; 2.3.0+ has best compatibility
KGP (built-in Kotlin runtime) 2.2.10 2.3.0+ AGP 9.0 has runtime dependency on KGP 2.2.10; auto-upgrades if lower
KSP 2.3.1 2.3.6 KSP version is no longer tied to the Kotlin compiler version since 2.3.0. AGP 9.0 and built-in Kotlin support added in 2.3.1. KSP migrated away from the deprecated compilerOptions KGP API in 2.3.3; earlier versions may have compatibility problems with other Gradle plugins
NDK — 28.2.13676358 Default changed to r28c; specify explicitly if needed
Android Studio Otter 3 (2025.2.3) Latest stable First version with full AGP 9.0 + KMP library plugin IDE support
IntelliJ IDEA Not supported — Does not support AGP 9.0 as of 2026.1, use Android Studio instead. Can still be used for non-Android KMP targets (JVM, iOS, JS/Wasm)
Max API Level — 36.1 Highest supported API level in AGP 9.0
Compose Multiplatform 1.9.3 1.10.0+ AGP 9.0 support was added in 1.9.3
Compose Compiler Plugin 2.0.0 Matches KGP version Since KGP 2.0, use org.jetbrains.kotlin.plugin.compose — version is tied to KGP automatically
Kotlin Coroutines 1.8.0 1.10.0+ 1.8.0+ for full K2 support
Kotlin Serialization 1.6.0 1.8.0+ 1.8.0+ for K2 compiler plugin support
Ktor 2.3.0 3.0.0+ 3.0.0 for best KMP library plugin compatibility
Room (KMP) 2.7.0 2.8.0+ KMP Room requires KSP; verify KSP compatibility

Version Notes

AGP 9.0.0

  • First release supporting com.android.kotlin.multiplatform.library.
  • Built-in Kotlin compilation for com.android.application and com.android.library (no separate kotlin-android plugin needed).
  • Removes support for com.android.application + org.jetbrains.kotlin.multiplatform in the same module.
  • Single-variant model for KMP libraries (no build types/flavors).
  • Runtime dependency on KGP 2.2.10 — projects using lower KGP versions are auto-upgraded.
  • If the project uses KSP, upgrade to 2.3.1+ for AGP 9.0 support.
  • New DSL interfaces only — BaseExtension and legacy types removed.
  • org.jetbrains.kotlin.kapt incompatible — use KSP or com.android.legacy-kapt.
  • Java source/target default changed from Java 8 to Java 11.
  • R class is compile-time non-final in application modules by default.
  • targetSdk defaults to compileSdk when not set (was minSdk).
  • NDK default changed to r28c.
  • Requires JDK 17+, Gradle 9.1.0+, SDK Build Tools 36.0.0.
  • Many Gradle property defaults changed — see SKILL.md "Gradle Properties Default Changes".
  • Removed: embedded Wear OS app support, density split APKs, legacy variant APIs.
  • New: IDE support for test fixtures, fused library plugin (preview).

AGP 9.0.1+

  • Bug fixes for KMP library plugin edge cases.
  • Improved error messages for common migration mistakes.
  • Better IDE sync performance.

KGP 2.3.0+

  • Best compatibility with KMP AGP 9.0 library plugin.
  • Improved multiplatform source set inference.
  • Better error diagnostics for KMP configuration issues.
  • Stable Compose compiler plugin integration.

Upgrade Path

From AGP 8.x + KGP 1.9.x

  1. Upgrade KGP to 2.0.0+ first (can be done on AGP 8.x).
  2. Migrate kotlinOptions to compilerOptions.
  3. Upgrade Gradle to 9.1.0.
  4. Upgrade AGP to 9.0.1+.
  5. Migrate library plugins to com.android.kotlin.multiplatform.library.
  6. Upgrade KGP to 2.3.0+ for best experience.

From AGP 8.x + KGP 2.0.x

  1. Upgrade Gradle to 9.1.0.
  2. Upgrade AGP to 9.0.1+.
  3. Migrate library plugins to com.android.kotlin.multiplatform.library.
  4. Upgrade KGP to 2.3.0+ for best experience.

gradle/wrapper/gradle-wrapper.properties

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

Basic libs.versions.toml template

[versions]
agp = "9.0.1"
kotlin = "2.3.20"
compose-multiplatform = "1.10.3"

[plugins]
androidApplication = { id = "com.android.application", version.ref = "agp" }
androidKmpLibrary = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
kotlinJvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "compose-multiplatform" }
composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

Compatibility Validation Commands

Run these to verify your setup is compatible:

# Check Gradle version
./gradlew --version

# Check AGP version applied
./gradlew buildEnvironment | grep -e "com.android.library" -e "com.android.application" -e "com.android.kotlin.multiplatform.library"

# Check KGP version
./gradlew buildEnvironment | grep "org.jetbrains.kotlin:kotlin-gradle-plugin"

# Verify the KMP library plugin is recognized
./gradlew :shared:tasks --group=build

# Full validation build
./gradlew :shared:assemble :androidApp:assembleDebug

Source: SKILL.md on GitHub

Third-party checks

No alerts16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides documentation and tools to assist in migrating Kotlin Multiplatform projects to Android Gradle Plugin (AGP) 9.0+. It includes guides for library modules, application splits, and a project analysis script. No security risks were identified.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer6mo

    5/10 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 43f4771. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 6 months ago

Capability

metadata
{
  "author": "JetBrains",
  "version": "1.0.0"
}

Topics

  • kotlin
  • kmp
  • agp
  • android-gradle-plugin
  • migrations
  • multiplatform
  • gradle
  • android

README badge

README badge for kotlin/kotlin-agent-skills/kotlin-tooling-agp9-migration

What it does

Migrates Kotlin Multiplatform projects to Android Gradle Plugin 9.0+, which requires separating the Android application plugin from KMP. Handles plugin replacement, DSL migration, module splitting, and directory structure updates for both library and application modules.

Generated from the current SKILL.md.

Frequently asked

Does this skill handle all KMP+AGP migration scenarios?
The skill covers three main paths: library modules (Path A), mandatory app+shared splits for AGP 9.0 (Path B), and recommended full restructures from monolithic modules (Path C). It assumes Kotlin Multiplatform projects; pure Android projects need only AGP version updates.
Do I need to remove the kotlin-android plugin?
Yes. AGP 9.0 has built-in Kotlin support, so org.jetbrains.kotlin.android must be removed from any module using AGP 9.0 plugins.
What happens to KAPT dependencies?
The skill identifies KAPT usage as incompatible with AGP 9.0. You must migrate to KSP or use com.android.legacy-kapt; the skill guides detection but does not automate the migration.
Do I need to rename my source directories?
Only if your module uses classic Android layout (src/main, src/test, src/androidTest). If it already uses KMP layout (src/androidMain, etc.), no directory renames are needed.
What Gradle and AGP versions does this target?
Gradle 9.1.0+ and AGP 9.0.0+. The skill includes gradle-wrapper updates and version catalog examples for both.

Generated from the current SKILL.md. These answers refresh after source changes.