AutoGineer
Generated banner for Agp 9 Upgrade
Generated logo for Agp 9 Upgrade

Agp 9 Upgrade

Android (Google)OfficialCreated by Google LLCDistributed by Android (Google)

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Upgrades, or migrates, an Android project to use Android Gradle Plugin (AGP) version 9. Do not use this skill for migrating Kotlin Multiplatform (KMP) projects.
— the description by Google LLC

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured workflow to upgrade Android projects to AGP 9. It handles the transition to built-in Kotlin support, updates dependencies like KSP and Hilt, migrates to the new AGP DSL, and cleans up obsolete properties in gradle.properties. It is designed for standard Android projects and explicitly excludes Kotlin Multiplatform (KMP) projects.

What it does

  • Updates project dependencies including KSP and Hilt to compatible versions.
  • Facilitates the migration to AGP 9 built-in Kotlin support.
  • Guides the transition to the new AGP DSL interfaces.
  • Assists in migrating from kapt to KSP or legacy-kapt.
  • Cleans up deprecated flags in gradle.properties.
  • Verifies the migration through Gradle sync and build checks.

When to use it

  • When you need to upgrade an existing Android project to AGP 9.
  • When you are ready to adopt built-in Kotlin support in your Android modules.
  • When your project requires migration to the new AGP 9 DSL interfaces.
  • When you need to update build dependencies to ensure compatibility with AGP 9.

Advantages

  • Simplifies complex build system migrations through a guided, step-by-step process.
  • Ensures project compatibility with the latest Android build tools and JDK requirements.
  • Reduces build configuration overhead by leveraging built-in Kotlin support.
  • Provides clear verification steps to ensure the project remains in a buildable state.

Usage examples

“Migrate my Android project to AGP 9.”
The agent will check your current AGP version, guide you through dependency updates, DSL changes, and built-in Kotlin migration, and verify the build.
“Help me update my app to use AGP 9 and the new DSL.”
The agent will initiate the migration workflow, ensuring your build files are updated to the new DSL interfaces and removing obsolete properties.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/android/agp-9-upgrade/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip agp-9-upgrade.zip -d .agents/skills

Documentation by Google LLC

Migration guide

See the AGP 9 migration guide for the major changes, many breaking, in AGP 9 compared to AGP 8.

Requirements

If the user requests to update or migrate to AGP 9, first check the AGP version used in the project. If it is lower than 9, stop and ask the user to run the AGP Upgrade Assistant in Android Studio to update to the latest stable version of AGP, and confirm when done. The user may also request that this requirement be skipped; if this is the case, you should update the version of AGP to the latest stable version as part of the AGP 9 migration. See the AGP 9 migration guide for how to do this.

Each version of AGP has its own set of compatibilities with other tools, such as Gradle, JDK, and Kotlin. The release notes for each of these versions will include a Compatibility table indicating the minimum versions for these tools.

Do not use this skill for KMP projects, as they are unsupported.

Steps

If AGP is already at 9 or higher, then do the following:

Step 1: Update dependencies

If KSP (com.google.devtools.ksp) is used in the project, ensure it is on version 2.3.6 or higher.

If Hilt is used in the project, ensure it is on version 2.59.2 or higher.

Step 2: Migrate to built-in Kotlin

See the guide for detailed information.

Step 3. Migrate to the new AGP DSL

See the guide for detailed information.

See also gradle-recipes for examples on how to migrate old code to code that is compatible with AGP 9 and the new DSL.

Step 4. Migrate kapt to KSP or legacy-kapt

If KSP (com.google.devtools.ksp) or kapt (org.jetbrains.kotlin.kapt) are used in the project, see KSP, kapt, and legacy-kapt for detailed migration steps.

Step 5. BuildConfig

If any Android module contains custom BuildConfig fields, see BuildConfig for detailed information.

Step 6. Update gradle.properties

After the migration, check gradle.properties. Remove the following flags:

  1. android.builtInKotlin

  2. android.newDsl

  3. android.uniquePackageNames

  4. android.enableAppCompileTimeRClass

Additionally, delete all temporary files you've created.

Guidelines

  • Never write or run python scripts.

  • Only search the Gradle dependency cache when inspecting external dependencies, and only as a last resort.

  • Never add android.disallowKotlinSourceSets=false to gradle.properties.

  • When verifying changes, don't run the clean task. This is a waste of time.

Verification

After migration, verify the following:

  1. Gradle IDE sync succeeds.

  2. ./gradlew help succeeds.

  3. ./gradlew build --dry-run succeeds.

Troubleshooting

Paparazzi v2.0.0-alpha04 and lower versions have issues with AGP 9. See references/paparazzi-gradle-9.md for details.

Files

references/ksp-kapt.md

When migrating to built-in Kotlin, it is important to consider usage of kapt and the org.jetbrains.kotlin.kapt (also known as the kotlin("kapt")) plugin. The goal is to migrate as many kapt usages to ksp as possible.

Follow these steps when migrating kapt:

1. Remove all references to the org.jetbrains.kotlin.kapt plugin

The org.jetbrains.kotlin.kapt (also known as kotlin("kapt")) plugin is incompatible with built-in Kotlin. Remove it when migrating to built-in Kotlin.

2. Check each usage of kapt

Check each usage of kapt to see if it is compatible with ksp. To check if a dependency is compatible with ksp, inspect the dependency's jar. For it to be compatible with ksp, the jar must have a file, services/com.google.devtools.ksp.processing.SymbolProcessorProvider. If it does not, it is incompatible with ksp.

For example, the androidx.room:room-compiler library is compatible with KSP since version 2.3.0-beta02. We can verify this by finding the jar file in the Gradle caches directory, which is typically located at ~/.gradle/caches/modules-2/files-2.1/ on Linux and Mac. In this specific case, the androidx.room:room-compiler dependency is located at ~/.gradle/caches/modules-2/files-2.1/androidx.room/room-compiler/.

More generally, you can find a dependency by looking in ~/.gradle/caches/modules-2/files-2.1/group-name/artifact-name/.

3. Migrate to KSP where possible

For each usage of kapt that is compatible with ksp, use ksp. The prior step explains how to check compatibility.

4. Apply legacy-kapt

If a Gradle module has kapt dependencies that cannot be migrated to ksp because they are incompatible (see step 2), then leave that dependency alone and apply the com.android.legacy-kapt plugin.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Google LLC
Publisher
Android (Google) (Official)
Distributed by
Android (Google)
Source
android/skills · build-system/agp/agp-9-upgrade · commit bf68e2d
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE.txt)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Google LLC or Android (Google).

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agp-9-upgrade.zip