Skip to content
Get packs

Guide · Agent skill

How to use the AGP 9 Upgrade Assistant agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The agp-9-upgrade skill is an agent skill from the Android skills repository that teaches an AI agent a step-by-step playbook for migrating an Android project to Android Gradle Plugin (AGP) 9. AGP is the build tool that compiles Android apps, and version 9 is a major release with many breaking changes. This guide explains what the skill does, how to install it, how to ask for it, and what to check before and after the agent runs.

AGP 9 Upgrade Assistantandroid/skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the agp-9-upgrade ZIP from this page and unzip it into ~/.claude/skills/ for a personal install or into .claude/skills/ in your project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  2. 2Confirm project eligibility. Make sure the project is an Android Gradle project and not a Kotlin Multiplatform project. Check that your Gradle and JDK versions are compatible with AGP 9.
  3. 3Ask the agent to upgrade. Start a request such as upgrade this Android project to AGP 9. The agent should load the skill because the request matches its description.
  4. 4Run the AGP Upgrade Assistant if asked. If the agent reports that AGP is below 9, open the project in Android Studio, run the AGP Upgrade Assistant to reach the latest stable AGP, and confirm to the agent when done.
  5. 5Review each change. Follow the agent through the six steps and check the edits to dependencies, build files, BuildConfig settings and gradle.properties.
  6. 6Run the verification checks. Confirm Gradle IDE sync succeeds, then run ./gradlew help and ./gradlew build --dry-run and make sure both succeed.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions, reference files and sometimes scripts that an AI coding agent can load when a task matches the skill's description. This one is written for upgrading an existing Android project to AGP 9.

Once the skill is active, the agent follows its steps in order. It checks the current AGP version, updates related tools such as KSP and Hilt, moves code to built-in Kotlin and the new build DSL, replaces kapt, updates BuildConfig and gradle.properties settings, and then runs verification commands.

How do you install the agp-9-upgrade skill?

Download the skill ZIP from this page and unzip it. You can put the skill in your user folder, where it applies to all of your projects, or in a single project.

For a personal install, unzip it into ~/.claude/skills/. For a project install, unzip it into the project's .claude/skills/ folder.

If you use the Claude apps instead, upload the ZIP under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP
~/.claude/skills/

Check your project before you start

The skill expects an Android project that uses Gradle with the Android Gradle Plugin. You also need a Gradle and JDK version that is compatible with the target AGP version. Android Studio is recommended, because the skill asks you to run the AGP Upgrade Assistant there in some cases.

The skill also relies on other tools only if your project already uses them: Kotlin, KSP, Hilt or Paparazzi.

The skill does not work for Kotlin Multiplatform (KMP) projects. The skill's own instructions say KMP projects are unsupported, so do not use it for them. The skill is also not meant for non-Android projects.

  • Android project using Gradle and Android Gradle Plugin
  • Gradle and a JDK compatible with the target AGP version
  • Android Studio recommended for the AGP Upgrade Assistant step
  • Kotlin, KSP, Hilt or Paparazzi only if already in use

How do you trigger the skill with a request?

Ask the agent in plain language to upgrade or migrate your project to AGP 9. The skill's description covers upgrading and migrating an Android project to AGP version 9, so requests like these match it.

The agent will first read the AGP version in your project. If it is lower than 9, it will stop and ask you to run the AGP Upgrade Assistant in Android Studio, then wait for you to confirm. You can ask the agent to skip that check, in which case it will update AGP to the latest stable version as part of the migration.

  • Upgrade this Android project to AGP 9.
  • Migrate my app module to Android Gradle Plugin 9.
  • Move this project to built-in Kotlin and the new AGP DSL.
  • Replace kapt with KSP in this Android app and update AGP to 9.

What steps does the agent follow?

When AGP is already at 9 or higher, the skill runs its steps in order. Each step points to a reference file with detailed guidance. The skill also contains guidelines for the agent, such as never writing or running Python scripts, and never running the clean task during verification.

Step 1 updates dependencies: KSP should be on version 2.3.6 or higher if used, and Hilt on 2.59.2 or higher if used. Step 2 migrates to built-in Kotlin, and Step 3 migrates to the new AGP DSL. Step 4 moves kapt to KSP or legacy-kapt. Step 5 handles BuildConfig fields. Step 6 removes four flags from gradle.properties and deletes temporary files the agent created.

  • Step 1: Update dependencies (KSP 2.3.6+, Hilt 2.59.2+)
  • Step 2: Migrate to built-in Kotlin
  • Step 3: Migrate to the new AGP DSL
  • Step 4: Migrate kapt to KSP or legacy-kapt
  • Step 5: Handle BuildConfig fields
  • Step 6: Remove android.builtInKotlin, android.newDsl, android.uniquePackageNames and android.enableAppCompileTimeRClass from gradle.properties

How do you verify the migration?

After the migration, the skill asks the agent to confirm three things. Gradle IDE sync should succeed, and the two Gradle commands below should both succeed. Run them yourself if you want an independent check.

If Paparazzi is in your project, note that Paparazzi v2.0.0-alpha04 and lower versions have known issues with AGP 9. The skill points to a separate reference file for those cases.

  • Gradle IDE sync succeeds
  • ./gradlew help succeeds
  • ./gradlew build --dry-run succeeds
./gradlew help ./gradlew build --dry-run

What people use it for

  • Moving an existing Android app module from an older AGP to AGP 9 with a checklist of breaking changes.
  • Replacing kapt with KSP or legacy-kapt as part of the same upgrade.
  • Moving build files to built-in Kotlin and removing the kotlin-android plugin where appropriate.
  • Cleaning up gradle.properties after the migration by removing the temporary flags listed in the skill.
  • Updating BuildConfig settings in modules that define custom BuildConfig fields.

Frequently asked questions

How do I install the agp-9-upgrade skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into .claude/skills/ inside your project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

What does the agp-9-upgrade skill need to run?

It needs an Android project that uses Gradle with the Android Gradle Plugin, plus a Gradle and JDK compatible with the target AGP version. Android Studio is recommended for the AGP Upgrade Assistant step, and Kotlin, KSP, Hilt or Paparazzi are only needed if your project already uses them.

Can I use this skill for a Kotlin Multiplatform project?

No. The skill says it must not be used for KMP projects because they are unsupported. The source points to a separate AGP 9 upgrade skill from JetBrains for KMP apps.

Is the agp-9-upgrade skill free?

The skill is released under the Apache-2.0 licence, as listed on this page. The SKILL.md file refers to a LICENSE.txt file for its complete terms, so read that file for the full conditions.

Does the skill use the network or run scripts?

This page lists that the skill runs scripts and does not use the network. The skill's own guidelines also tell the agent never to write or run Python scripts.

What should I do if the agent says my AGP version is too old?

Open the project in Android Studio and run the AGP Upgrade Assistant to update to the latest stable AGP version. Then confirm to the agent that this is done so it can continue. You can also tell the agent to skip this check, and it will update AGP as part of the migration.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are an Android developer with an existing non-KMP app that needs to move to AGP 9, and you already work with an AI agent in your project. Skip it for Kotlin Multiplatform projects, for non-Android projects, and for older AGP projects you have not first upgraded with Android Studio's Upgrade Assistant.

Download the skill