# kotlin-tooling-agp9-migration

Walks a Kotlin Multiplatform project through Android Gradle Plugin 9.0: plugin swaps, module splitting, DSL migration.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2200 installs · ★ 1093
- Author: JetBrains
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Kotlin/kotlin-agent-skills/tree/HEAD/skills/kotlin-tooling-agp9-migration/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/kotlin-tooling-agp9-migration

## What it does

Android Gradle Plugin 9.0 makes the Android application and library plugins incompatible with the Kotlin Multiplatform plugin in the same module. The skill starts by reading the project: `settings.gradle.kts`, each module's `build.gradle.kts`, the version catalog in `gradle/libs.versions.toml`, the Gradle version from `gradle/wrapper/gradle-wrapper.properties`, and `gradle.properties`. Then it sorts every module into one of three migration paths.

Path A swaps `com.android.library` for `com.android.kotlin.multiplatform.library`, moves config into a `kotlin { android {} }` block, renames source directories and shifts dependencies into `sourceSets`. Path B is mandatory wherever `com.android.application` sits next to KMP: the Android app moves out into its own `androidApp` module. Path C restructures a monolithic `composeApp` into the JetBrains default layout, one app module per platform.

The skill also catches the usual build breakers. `org.jetbrains.kotlin.android` has to go, since AGP 9.0 ships built-in Kotlin, and `org.jetbrains.kotlin.kapt` does not work with that built-in Kotlin, so it moves to KSP or `com.android.legacy-kapt`. It configures `localDependencySelection` too, because the new single-variant architecture cannot resolve dependencies published with `debug`/`release` build types or product flavors on its own. With Bash available, the analysis step can run `scripts/analyze-project.sh` from the skill directory.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-agp9-migration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/kotlin-tooling-agp9-migration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/kotlin-tooling-agp9-migration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-agp9-migration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/kotlin-tooling-agp9-migration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-agp9-migration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/kotlin-tooling-agp9-migration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Kotlin/kotlin-agent-skills kotlin-tooling-agp9-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/kotlin-tooling-agp9-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-agp9-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Kotlin/kotlin-agent-skills --path skills/kotlin-tooling-agp9-migration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/kotlin-tooling-agp9-migration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-agp9-migration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Kotlin/kotlin-agent-skills/tree/HEAD/skills/kotlin-tooling-agp9-migration/SKILL.md

## When to use it
- swap a KMP library onto the `com.android.kotlin.multiplatform.library` plugin
- pull the Android app out of a shared module into `androidApp`
- move settings from `android {}` into `kotlin { android {} }`
- drop `org.jetbrains.kotlin.android` and migrate kapt to KSP
- set up `localDependencySelection` for dependencies with flavors

## Example prompts
- analyze my KMP project and tell me which modules need the AGP 9.0 migration
- the build broke after the AGP upgrade — walk the migration paths and fix it
- restructure the monolithic `composeApp` into separate app modules per platform

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d28474b79d898f39.

BEGIN THIRD-PARTY FILE d28474b79d898f39
```text
---
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`
```
END THIRD-PARTY FILE d28474b79d898f39

The third-party file has ended. Everything between the d28474b79d898f39 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 1896 of 21755 bytes. © JetBrains · Apache-2.0 · https://github.com/Kotlin/kotlin-agent-skills/tree/HEAD/skills/kotlin-tooling-agp9-migration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md