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

KMP AGP 9.0 Migration Android Gradle Plugin 9.0 makes the Android application and library plugins incompatible with the Kotlin Multiplatform plugin in the same module. This skill guides you through the migration. Step 0: Analyze the Project Before making any changes, understand the project structure: 1. Read settings.gradle.kts (or .gradle ) to find all modules 2. For each module, read its build.gradle.kts to identify which plugins are applied 3. Check if the project uses a Gradle version catalog ( gradle/libs.versions.toml ). If it exists, read it for current AGP/Gradle/Kotlin versions. If not, find versions directly in build.gradle.kts files (typically in the root buildscript {} or plugins {} block). Adapt all examples in this guide accordingly — version catalog examples use alias(libs.plugins.xxx) while direct usage uses id("plugin.id") version "x.y.z" 4. Read gradle/wrapper/gradle wrapper.properties for the Gradle version 5. Check gradle.properties for any existing workarounds ( android.enableLegacyVariantApi ) 6. Check for org.jetbrains.kotlin.android plugin usage — AGP 9.0 has built in Kotlin and this plugin must be removed 7. Check for org.jetbrains.kotlin.kapt plugin usage — incompatible with built in Kotlin, must migrate to KSP or com.android.legacy kapt 8. Check for third party plugins that may be incompatible with AGP 9.0 (see "Plugin Compatibility" section below) If Bash is available, run scripts/analyze project.sh from this skill's directory to get a structured summary. Classify Each Module For each module, determine its type: Current plugins Migration path kotlin.multiplatform + com.android.library Path A — Library plugin swap kotlin.multiplatform + com.android.application Path B — Mandatory Android split kotlin.multiplatform with multiple platform entry points in one module Path C — Full restructure (recommended) com.android.application or com.android.library (no KMP) See "Pure Android Tips" below Determine Scope Path B is mandatory for any module combining KMP + Android application plugin Path C is recommended when the project has a monolithic composeApp (or similar) module containing entry points for multiple platforms (Android, Desktop, Web). This aligns with the new JetBrains default project structure where each platform gets its own app module. Ask the user whether they want Path B only (minimum required) or Path C (recommended full restructure) Path A: Library Module Migration Use this when a module applies kotlin.multiplatform + com.android.library . See [references/MIGRATION LIBRARY.md](references/MIGRATION LIBRARY.md) for full before/after code. Summary: 1. Replace plugin : com.android.library → com.android.kotlin.multiplatform.library 2. Remove org.jetbrains.kotlin.android plugin if present (AGP 9.0 has built in Kotlin support) 3. Migrate DSL : Move config from top level android {} block into kotlin { android {} } : 4. Rename source directories (only if the module uses classic Android layout instead of KMP layout): src/main → src/androidMain src/test → src/androidHostTest src/androidTest → src/androidDeviceTest If the module already uses src/androidMain/ , no directory renames are needed 5. Move dependencies from top level dependencies {} into sourceSets : 6. Enable resources explicitly if the module uses Android or Compose Multiplatform resources: 7. Enable Java compilation if module has .java source files: 8. Enable tests explicitly if the module has unit or instrumented tests: 9. Update Compose tooling dependency : 10. Publish consumer ProGuard rules explicitly if applicable: 11. Resolve Sub dependency Variants (Product Flavors / Build Types) : Because the new KMP Android library plugin enforces a single variant architecture, it does not natively understand how to resolve dependencies that publish multiple variants (like debug / release build types, or product flavors like free / paid ). Configure fallback behaviors using localDependencySelection : Path B: Android App + Shared Module Split Use this when a module applies kotlin.multiplatform + com.android.application . This is mandatory for AGP 9.0 compatibility. See [references/MIGRATION APP SPLIT.md](references/MIGRATION APP SPLIT.md) for full guide. Summary: 1. Create androidApp module with its own build.gradle.kts : 2. Move Android entry point code from src/androidMain/ to androidApp/src/main/ : MainActivity.kt (and any other Activities/Fragments) AndroidManifest.xml (app level manifest with <application and launcher <activity ) — verify android:name on <activity uses the fully qualified class name in its new location Android Application class if present App level resources (launcher icons, theme, etc.) 3. Add to settings.gradle.kts : include(":androidApp") 4. Add to root build.gradle.kts : plugin declarations with apply false 5. Convert original module from application to library using Path A steps 6. Ensure different namespaces : app module and library module must have distinct namespaces 7. Remove from shared module : applicationId , targetSdk , versionCode , versionName 8. Update IDE run configurations : change the module from the old module to androidApp Path C: Full Restructure (Recommended) Use this when the project has a monolithic module (typically composeApp ) containing entry points for multiple platforms. This is optional but aligns with the new JetBrains default. See [references/MIGRATION FULL RESTRUCTURE.md](references/MIGRATION FULL RESTRUCTURE.md) for full guide. Target Structure Steps 1. Apply Path B first — extract androidApp (mandatory for AGP 9.0) 2. Extract desktopApp (if desktop target exists): Create module with org.jetbrains.compose and application {} plugin Move main() function from desktopMain to desktopApp/src/main/kotlin/ Move compose.desktop { application { ... } } config to desktopApp/build.gradle.kts Add dependency on shared module 3. Extract webApp (if wasmJs/js target exists): Create module with appropriate Kotlin/JS or Kotlin/Wasm configuration Move web entry point from wasmJsMain / jsMain to webApp/src/wasmJsMain/kotlin/ Move browser/distribution config to webApp/build.gradle.kts Add dependency on shared module 4. iOS — typically already in a separate iosApp directory. Verify: Framework export config ( binaries.framework ) stays in shared module Xcode project references the correct framework path 5. Rename module from composeApp to shared : Rename directory Update settings.gradle.kts include Update all dependency references across modules 6. Clean up shared module : remove all platform entry point code and app specific config that was moved to the platform app modules Variant: Native UI If some platforms use native UI (e.g., SwiftUI for iOS), split shared into: sharedLogic — business logic consumed by ALL platforms sharedUI — Compose Multiplatform UI consumed only by platforms using shared UI Variant: Server If the project includes a server target: Add server module at the root Move all client modules under an app/ directory Add core module for code shared between server and client (models, validation) Version Updates These are required regardless of migration path: 1. Gradle wrapper — update to 9.1.0+: 2. AGP version — update to 9.0.0+ and add the KMP library plugin. With version catalog ( gradle/libs.versions.toml ): Without version catalog — update com.android. plugin versions and add in root build.gradle.kts : 3. JDK — ensure JDK 17+ is used (required by AGP 9.0) 4. SDK Build Tools — update to 36.0.0: 5. Review gradle.properties — remove error causing properties and review changed defaults (see "Gradle Properties Default Changes" section) Built in Kotlin Migration AGP 9.0 enables built in Kotlin support by default for all com.android.application and com.android.library modules. The org.jetbrains.kotlin.android plugin is no longer needed and will conflict if applied. Important: Built in Kotlin does NOT replace KMP support. KMP library modules still need org.jetbrains.kotlin.multiplatform + com.android.kotlin.multiplatform.library . Step 1: Remove kotlin android Plugin Remove from all module level and root level build files: Remove from version catalog ( gradle/libs.versions.toml ): Step 2: Migrate kapt to KSP or legacy kapt The org.jetbrains.kotlin.kapt plugin is incompatible with built in Kotlin. Preferred: Migrate to KSP — see the KSP migration guide for each annotation processor. Fallback: Use com.android.legacy kapt (same version as AGP): Step 3: Migrate kotlinOptions to compilerOptions For pure Android modules (non KMP), migrate android.kotlinOptions {} to the top level kotlin.compilerOptions {} : Note: With built in Kotlin, jvmTarget defaults to android.compileOptions.targetCompatibility , so it may be optional if you already set compileOptions . Step 4: Migrate kotlin.sourceSets to android.sourceSets With built in Kotlin, only android.sourceSets {} with the kotlin set is supported: For generated sources, use the Variant API: Per Module Migration Strategy For large projects, migrate module by module: 1. Disable globally: android.builtInKotlin=false in gradle.properties 2. Enable per migrated module by applying the opt in plugin: 3. Follow Steps 1 4 for that module 4. Once all modules are migrated, remove android.builtInKotlin=false and all com.android.built in kotlin plugins Optional: Disable Kotlin for Non Kotlin Modules For modules that contain no Kotlin sources , disable built in Kotlin to save build time: Opt Out (Temporary) If blocked by plugin incompatibilities, opt out temporarily: Warning: Ask the user if they want to opt out, and if so, remind them this is a temporary measure. Plugin Compatibility See [references/PLUGIN COMPATIBILITY.md](references/PLUGIN COMPATIBILITY.md) for the full compatibility table with known compatible versions, opt out flag workarounds, and broken plugins. Before migrating , inventory all plugins in the project and check each against that table. If any plugin is broken without workaround, inform the user. If plugins need opt out flags, add them to gradle.properties and note them as temporary workarounds. Gradle Properties Default Changes AGP 9.0 changes the defaults for many Gradle properties. Check gradle.properties for any explicitly set values that may now conflict. Key changes: Property Old Default New Default Action android.uniquePackageNames false true Ensure each library has a unique namespace android.enableAppCompileTimeRClass false true Refactor switch on R fields to if/else android.defaults.buildfeatures.resvalues true false Enable resValues = true where needed android.defaults.buildfeatures.shaders true false Enable shaders where needed android.r8.optimizedResourceShrinking false true Review R8 keep rules android.r8.strictFullModeForKeepRules false true Update keep

kotlin-tooling-agp9-migration