kotlin-tooling-agp9-migration

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: instruction override, no behavioural pass.

**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`gr

3. **If any plugin is broken without workaround**, inform the user — they may need to wait for a plugin update or remove it

plugins/kotlin-agent-skills/skills

Audit 0.4.1 · source sha 25b8117b6cd6 · 21 Oct 2026Report an issue or request a re-scan

• Publisherkotlin GitHub organizationOwner of the repository this skill is read from
• Source folderkotlin/kotlin-agent-skills/skills/kotlin-tooling-agp9-migrationThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict25b8117b6cd6A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 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.…

---
name: kotlin-tooling-agp9-migration
description: >
  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.
license: Apache-2.0
metadata:
  author: JetBrains
  version: "1.0.0"
---

# 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 {} }`:
   ```kotlin
   kotlin {
       android {
           namespace = "com.example.lib"
           compileSdk = 35
           minSdk = 24
       }
   }
   ```
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`:
   ```kotlin
   kotlin {
       sourceSets {
           androidMain.dependencies {
               implementation("androidx.appcompat:appcompat:1.7.0")
           }
       }
   }
   ```
6. **Enable resources** explicitly if the module uses Android or Compose Multiplatform resources:
   ```kotlin
   kotlin {
       android {
           androidResources { enable = true }
       }
   }
   ```
7. **Enable Java** compilation if module has `.java` source files:
   ```kotlin
   kotlin {
       android {
           withJava()
       }
   }
   ```
8. **Enable tests** explicitly if the module has unit or instrumented tests:
   ```kotlin
   kotlin {
       android {
           withHostTest { isIncludeAndroidResources = true }
           withDeviceTest {
               instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
           }
       }
   }
   ```
9. **Update Compose tooling dependency**:
   ```kotlin
   // Old: 
   debugImplementation(libs.androidx.compose.ui.tooling)
   // New:
   androidRuntimeClasspath(libs.androidx.compose.ui.tooling)
   ```
10. **Publish consumer ProGuard rules** explicitly if applicable:
    ```kotlin
    kotlin {
        android {
            consumerProguardFiles.add(file("consumer-rules.pro"))
        }
    }
    ```
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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/kotlin/kotlin-agent-skills
git -C kotlin-agent-skills checkout 25b8117b6cd6

Works in

1. 2026-10-21
   ✕BLOCK D 69 / 100

   first audit · source 25b8117b6cd6

Questions about kotlin-tooling-agp9-migration

• github.com/kotlin/kotlin-agent-skills/tree/main/skills/kotlin-to — the audited source at commit 25b8117b6cd6 and every finding aboveObserved · 21 Oct 2026

Spotted something wrong? Report a correction · Methodology