upgrade-android-sdk

Type	Skill
Plugin	awl-android · v0.0.19
Invoke	/awl-android:upgrade-android-sdk
Tools	Read, Write, Edit, Bash, Glob, Grep
Source	plugins/awl-android/skills/upgrade-android-sdk/SKILL.md

When Claude uses it

This skill should be used when the user asks to “upgrade to SDK 37”, “target Android 17”, “bump targetSdk/compileSdk”, “Android 17 migration”, “upgrade the android sdk”, or “update android target”. It upgrades an Android project from SDK 33–36 to SDK 37 (Android 17): bumps build files, auto-applies breaking-change code fixes, builds, runs unit tests, validates the large-screen resizability mandate on phone + tablet emulators via Android CLI, and reports everything that needs manual verification.

Trigger phrases: upgrade to SDK 37 · target Android 17 · bump targetSdk/compileSdk · Android 17 migration · upgrade the android sdk · update android target

Definition

Upgrade an Android project whose targetSdk is currently 33, 34, 35, or 36 to SDK 37 (Android 17). Apply every breaking-change fix that can be made mechanically, detect-and-report the risky ones, build, test, and validate the resizability mandate on a phone and a tablet emulator. All device, SDK, and build-artifact work goes through the android CLI.

This skill auto-fixes aggressively. When a fix cannot be applied safely (reflection, native libraries, runtime-only behavior), flag it in the final report instead of guessing.

Prerequisites

• The android CLI must be installed: command -v android. If absent, stop and tell the developer to run the install from the android-cli skill.
• Work on a clean git tree. If the tree is dirty, warn the developer and offer to stop — the upgrade edits many files.

Workflow

Step 0 — Locate and snapshot

Resolve the project root (CLI argument or current directory). Confirm it is a git repo and committed/clean. Note the head commit so the developer can diff/revert.

Step 1 — Detect current state

Run the deterministic scanner first; it greps the whole project for every pattern this upgrade cares about and prints them with file:line:

bash "${CLAUDE_PLUGIN_ROOT}/skills/upgrade-android-sdk/scripts/scan.sh" <project_dir>

Then read build configuration to record exact versions:

• android describe --project_dir <dir> → it emits paths to JSON files (not inline data). Read those JSON files to map the app module(s) and the APK output paths (needed in Step 7).
• Read build.gradle(.kts) (root + each module), gradle/libs.versions.toml, settings.gradle(.kts), gradle/wrapper/gradle-wrapper.properties, and every AndroidManifest.xml.
• Record compileSdk, targetSdk, minSdk, AGP version, Gradle version, Kotlin version, and whether the UI is Compose or XML Views.

The source targetSdk decides which catch-up fixes apply (see references/breaking-changes.md):

• 36 → only the SDK 37 changes.
• 35 → SDK 37 changes.
• 34 → SDK 37 + SDK 35 catch-up.
• 33 → SDK 37 + SDK 35 + SDK 34 catch-up.

Step 2 — Ensure the SDK 37 toolchain

android sdk list "platforms*"

If platforms/android-37.0 is missing, install it plus a system image and matching build-tools:

android sdk install platforms/android-37.0
android sdk list "system-images*android-37*"     # pick an installed/available image id
android sdk install system-images/android-37.0/google_apis_playstore_ps16k/arm64-v8a

SDK 37 requires a minimum AGP/Gradle/Kotlin. Look up the current minimum with android docs search "AGP compileSdk 37 minimum version" and bump AGP, the Gradle wrapper, and Kotlin if the project is below it. Do this before building.

Step 3 — Bump the build files

Set compileSdk = 37 and targetSdk = 37. Leave minSdk untouched. Edit wherever the project declares them — gradle/libs.versions.toml (a [versions] entry) or the module build.gradle(.kts). Match the project’s existing style.

Step 4 — Apply breaking-change fixes

Work through references/breaking-changes.md top to bottom, gated by the source targetSdk from Step 1. Each entry says whether to auto-fix or detect + report. Use the scanner output from Step 1 as the worklist. Record every change (and every flagged item) for the Step 8 report.

Step 5 — Build

Run the project’s own wrapper:

./gradlew :app:assembleDebug        # plus :<module>:assembleDebug for other app modules

Iterate on compile errors. Anything that cannot be resolved mechanically goes into the report with the error text.

Step 6 — Unit tests

./gradlew testDebugUnitTest

Watch specifically for failures caused by the SDK 37 runtime lockdown: reflection that writes static final fields, and reflection into MessageQueue — common in mocking/DI frameworks and test doubles. Report pass/fail with the relevant output.

Step 7 — Phone + tablet validation

The resizability mandate is the headline SDK 37 change, so the app must be exercised on both form factors. Follow references/test-phone-tablet.md:

1. Create/start a medium_phone and a medium_tablet AVD on the API-37 image.
2. Deploy the APK (path from Step 1’s describe JSON) to each with android run --apks <apk> --device <serial>.
3. Walk the key screens, capturing android screen capture -o PNGs on the phone, then the tablet.
4. Compare phone vs tablet per screen. The tablet must be usable — no off-screen action buttons, no clipping, no broken blank regions. Optimization is not required.

Flag any tablet layout breakage with the screen name in the report.

Step 8 — Report

Produce a single summary:

• Changes made — file-by-file (build files, manifest, code).
• Build — pass/fail + unresolved errors.
• Unit tests — pass/fail + reflection-related failures.
• Phone vs tablet — per-screen assessment with the screenshot paths.
• Manual TODO — every detect-and-report item plus anything not auto-verifiable (reflection in third-party deps, native .so read-only requirement, background audio at runtime, keystore caps, local-network at runtime, FGS timeout behavior, recreateOnConfigChanges decisions, edge-to-edge visual review). Each item names the file(s) and the SDK-37 reason.

State plainly what was verified versus what the developer must still test by hand.

Resources

• scripts/scan.sh — deterministic detector. Greps the project for every breaking-change pattern (manifest attributes, reflection, native loads, cleartext, services, receivers, insets) and prints file:line findings grouped by change. Run it in Step 1 and use its output as the fix worklist.
• references/breaking-changes.md — per-change detection + fix recipes for SDK 37 and the SDK 35 / SDK 34 catch-up changes, each marked auto-fix or detect-and-report.
• references/test-phone-tablet.md — the Android CLI emulator + screenshot comparison workflow, including the android command quirks (e.g. screen capture has no --device flag).