AGP 9 Upgrade

Organization

android

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.

Overview

Repository: android/skills
Publisher: android
Stars: 10.5K
Forks: 695
Bundled files: 6
License: Apache-2.0
Updated: Nov 11, 2026
Links: Skill source Repository

Installation

tmp=$(mktemp -d)
git clone --depth 1 https://github.com/android/skills.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/build-system/agp/agp-9-upgrade" ~/.claude/skills/agp-9-upgrade
rm -rf "$tmp"

tmp=$(mktemp -d)
git clone --depth 1 https://github.com/android/skills.git "$tmp"
mkdir -p ~/.codex/skills
cp -R "$tmp/build-system/agp/agp-9-upgrade" ~/.codex/skills/agp-9-upgrade
rm -rf "$tmp"

Install the AGP 9 Upgrade agent skill from https://github.com/android/skills/tree/main/build-system/agp/agp-9-upgrade into this project's skills folder.

Instructions

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:

android.builtInKotlin
android.newDsl
android.uniquePackageNames
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:

Gradle IDE sync succeeds.
./gradlew help succeeds.
./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.

Bundled files

FAQ

What does AGP 9 Upgrade do?

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.

Who made AGP 9 Upgrade?

android (an organization) publishes it in the android/skills repository on GitHub.

Is AGP 9 Upgrade free?

Yes. AGP 9 Upgrade is open source, published by android under the Apache-2.0 license.

What comes with AGP 9 Upgrade?

Its instructions and 6 files the agent reads only when a task needs them, such as references, examples or scripts.

Which agents can use AGP 9 Upgrade?

Any coding agent that reads SKILL.md files, including Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI. The agent loads the skill when a task matches its description.

What are agent skills?

An agent skill is a folder with a SKILL.md file: instructions that teach a coding agent how to do one kind of task, and optionally files it can read while it works. The agent keeps only the skill's name and description in mind and reads the rest when a task calls for it.

How are agent skills different from MCP servers?

An MCP server gives an agent new tools to call, code that runs somewhere and returns results. A skill gives it knowledge: how to approach a task with the tools it already has. Many agents use both.

How can my agent test my Android app?

Robomori lets coding agents create, start and control Android emulators and devices from one command, so they can install your app, take screenshots and check dark mode, font sizes and languages.