android-toolchain-upgrade

Upgrades Android Gradle, AGP, Kotlin, KSP, and Compose versions with per-step build gates.

Updated Aug 10, 2026
One-click install
npx skills add https://github.com/nolte/claude-android-engineering --skill android-toolchain-upgrade-nolte
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: android-toolchain-upgrade
Source: https://github.com/nolte/claude-android-engineering/tree/main/skills/android-toolchain-upgrade
Command: npx skills add https://github.com/nolte/claude-android-engineering --skill android-toolchain-upgrade-nolte

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Keeping an existing Android project's toolchain current is risky because Gradle, AGP, Kotlin, KSP, and the Compose BOM form a coupled version matrix, and a wrong bump silently breaks the build or misses Play targetSdk deadlines. This Skill inventories the current toolchain, researches compatible versions from primary sources, plans an ordered upgrade path, and applies each step behind a green ./gradlew build gate. ## Core Features & Use Cases - Three operations: audit (read-only currency report with severities), plan (researched, ordered upgrade path), and apply (one confirmed, build-gated step at a time). - Coupling-aware upgrades: handles AGP↔Gradle↔Kotlin↔KSP↔Compose constraints, the AGP 9 built-in-Kotlin migration, kapt removal, and targetSdk behaviour-change walks. - Verification and logging: checks 16 KB page-size alignment on release artifacts, runs osv-scanner and Renovate hygiene checks, and records every run in a toolchain log. - Use Case: Ask it to raise AGP, Kotlin, and targetSdk on an existing app; it inventories versions, fetches current compatibility facts, walks the targetSdk behaviour changes, and applies each bump only after the previous build stays green. ## Quick Start Ask the assistant to update the Android project's AGP, Kotlin, and targetSdk to current compatible versions using the android-toolchain-upgrade skill.

Frequently Asked Questions about android-toolchain-upgrade

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I upgrade AGP, Gradle, and Kotlin in an Android project safely?

Inventory the current versions, research the AGP↔Gradle↔Kotlin↔KSP↔Compose coupling from primary sources, then apply bumps in canonical order: wrapper, AGP, the Kotlin line together, then SDK levels and libraries. Gate every step with ./gradlew build and never continue on a red build.

How to migrate an Android project to AGP 9 built-in Kotlin?

Remove org.jetbrains.kotlin.android from every module, move KGP DSL like kotlinOptions to the AGP-owned equivalents, and switch kapt processors to KSP artefacts. Where no KSP path exists, apply com.android.legacy-kapt as a recorded interim, never org.jetbrains.kotlin.kapt.

Does KSP version need to match the Kotlin version?

Yes, KSP must support the project's Kotlin version. Below KSP 2.3.0 the release prefix equals the Kotlin version; from 2.3.0 KSP is versioned independently and each release names its supported Kotlin range, which must be checked before bumping.

What must be handled before bumping targetSdk?

Walk the behaviour-changes page for every level between current and target, resolving predictive back, edge-to-edge enforcement, orientation rules, foreground-service types, and permission or notification changes. Apply the bump only when each impact is fixed, handed over, or recorded as a dated interim.

How do I verify 16 KB page-size alignment of native libraries?

Set useLegacyPackaging = false, build the release APK or AAB, then run check_elf_alignment.sh or zipalign -c -P 16 -v 4 on the artifact. Every LOAD segment of each .so must be aligned to 2**14 or higher; unaligned libraries need a dependency version shipping 16 KB builds.

When should I not use this toolchain upgrade skill?

Do not use it to scaffold a new project, to fix a build that is red for unrelated reasons, or to run the full release-readiness audit. Those cases route to android-project-scaffold, android-debugging, and android-release-readiness-reviewer respectively.