---
name: android-agp-upgrade
description: Upgrade an Android project to Android Gradle Plugin (AGP) 9. Use when migrating to AGP 9, updating Gradle build files, migrating to built-in Kotlin, or adopting the new AGP DSL.
metadata:
  triggers:
    files:
    - 'build.gradle.kts'
    - 'build.gradle'
    - 'settings.gradle.kts'
    - 'gradle.properties'
    keywords:
    - AGP 9
    - AGP upgrade
    - Gradle plugin
    - built-in Kotlin
    - new DSL
    - migrate AGP
  upstream:
    - name: agp
      source: manual
      pinned: "9.0.0"
      reviewed: "2026-07-09"
---
# AGP 9 Upgrade Workflow

## **Priority: P1 (HIGH)**

Step-by-step workflow for upgrading an Android project to AGP 9.

## Prerequisites

- Check current AGP version. If below 8.x, recommend running the AGP Upgrade Assistant in Android Studio first.
- Do NOT use this skill for Kotlin Multiplatform (KMP) projects.
- Verify Gradle, JDK, and Kotlin version compatibility with AGP 9 release notes.

## Step 1: Update dependencies

- If KSP (`com.google.devtools.ksp`) is used, ensure version 2.3.6+.
- If Hilt is used, ensure version 2.59.2+.
- Update AGP to the latest stable 9.x version in the project's build files.

## Step 2: Migrate to built-in Kotlin

AGP 9 includes built-in Kotlin support — the `org.jetbrains.kotlin.android` plugin is no longer needed.

See [migration guide](references/built-in-kotlin.md) for detailed steps.

## Step 3: Migrate to the new AGP DSL

AGP 9 introduces a new DSL for `android {}` blocks. Key changes include namespace handling, build type configuration, and source set declarations.

See [DSL migration](references/dsl-migration.md) for before/after examples.

## Step 4: Migrate kapt to KSP or legacy-kapt

If the project uses `kapt`:
- Prefer migrating to KSP where annotation processors support it (Room, Hilt, Moshi).
- For processors without KSP support, use `legacy-kapt` as a bridge.

## Step 5: Update BuildConfig

If any module uses custom `BuildConfig` fields, update to the new AGP 9 syntax.

## Step 6: Clean up gradle.properties

Remove these flags after migration:
1. `android.builtInKotlin`
2. `android.newDsl`
3. `android.uniquePackageNames`
4. `android.enableAppCompileTimeRClass`

## Guidelines

- Never write or run Python scripts for build migration.
- Never add `android.disallowKotlinSourceSets=false` to `gradle.properties`.
- Do not run `clean` task when verifying — it wastes time.

## Verification

1. `./gradlew help` succeeds.
2. `./gradlew build --dry-run` succeeds.
3. Gradle IDE sync succeeds.

## References

- [Built-in Kotlin Migration](references/built-in-kotlin.md)
- [DSL Migration Guide](references/dsl-migration.md)