claude-android-ninja — Claude Code skill for Android apps

---
name: claude-android-ninja
description: Build and migrate Android apps with Kotlin, Jetpack Compose, MVVM, Hilt, Room 3 (KSP, SQLiteDriver, Flow/suspend DAOs), Navigation3, and multi-module Gradle. Use for new projects or modules, Compose screens and ViewModels, Room 3 and RemoteMediator, API 37 / targetSdk migration, Play Integrity client wiring, offline-first sync, and version-catalog alignment. Not for iOS, Flutter, React Native, KMP-only shared code without an Android app module, or backend-only APIs with no Android client.
compatibility: JDK 17+. Android Studio with Android SDK installed. Network access for Gradle dependency downloads. Version pins in assets/templates follow the repo catalog; align AGP/Kotlin/KSP with the user project before applying upgrades.
license: Apache-2.0
metadata:
  author: DrJacky
  version: "1.0.0"
  documentation: https://github.com/Drjacky/claude-android-ninja
  tags: android, kotlin, compose, mvvm, hilt, room, room3, datastore, paging, gradle, mobile
---
# Android Kotlin Compose Development

**Context ladder (smaller load first; full references stay complete):**

1. This file (`SKILL.md`) - routing, stop rules, examples.
2. `references/*-quick.md` when listed below - required/forbidden + section links (~40 lines).
3. One target section in the full `references/*.md` - code samples and checklists only.
4. [INDEX-sections.md](references/INDEX-sections.md) - anchor dump only when quick routing is insufficient.

Forbidden: load [INDEX-sections.md](references/INDEX-sections.md) or an entire multi-thousand-line reference when one section or a quick file covers the task.

Route tasks through the Quick Reference table. When no row matches, or the task needs greenfield bootstrap: [workflows.md](references/workflows.md). Full file list: [INDEX.md](references/INDEX.md).

**Required:**

- **Existing project:** read `settings.gradle.kts`, `gradle/libs.versions.toml`, and the `app` module build file before copying from `assets/` - [dependencies.md](references/dependencies.md#existing-project-brownfield), [modularization.md](references/modularization.md#existing-project-alignment). Stack migrations: [migration.md](references/migration.md).
- **Greenfield:** [workflows.md](references/workflows.md) → "Creating a new project?"
- After module, DI, navigation, Room schema, or AGP/Kotlin/KSP changes: `./gradlew help` then `:app:assembleDebug` (use the real app module name) - [gradle-setup.md](references/gradle-setup.md#verify-after-toolchain-or-module-changes).

**Outside-repo stop rules (do not substitute repo edits):** Play upload, tracks, rollout, `versionCode` - [android-ci-cd.md](references/android-ci-cd.md); Play Integrity prerequisites (Console/Cloud setup) - [android-security-quick.md](references/android-security-quick.md); production `adb install` / `pm clear` - [testing.md](references/testing.md#agent-automation-adb-and-uiautomator).

## Quick Reference

Rare or niche topics not listed here are in [INDEX.md](references/INDEX.md) (complete file list).

| Task                                                                                                           | Reference                                                                                                                                                                                                     |
|----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Task not in table, greenfield bootstrap, multi-topic setup                                                     | [workflows.md](references/workflows.md)                                                                                                                                                                       |
| Optional Android CLI project discovery, Studio checks, preview, and test-device inspection                     | [workflows.md](references/workflows.md) ("Using the optional Android CLI for agent workflows?")                                                                                                               |
| Full index of all reference files                                                                              | [INDEX.md](references/INDEX.md)                                                                                                                                                                               |
| Version catalog, pins, alpha policy, brownfield alignment                                                      | [dependencies.md](references/dependencies.md#version-strategy)                                                                                                                                                |
| Adding or updating dependencies (catalog aliases)                                                              | [dependencies.md](references/dependencies.md)                                                                                                                                                                 |
| Multi-module dependencies                                                                                      | [dependencies.md](references/dependencies.md)                                                                                                                                                                 |
| Project structure and modules                                                                                  | [modularization.md](references/modularization.md)                                                                                                                                                             |
| MVVM layers, repositories, DI                                                                                  | [architecture.md](references/architecture.md)                                                                                                                                                                 |
| Retrofit / OkHttp, NetworkModule, nullable DTOs, AuthInterceptor                                               | [architecture.md](references/architecture.md#network-layer-setup-corenetwork); [dependencies.md](references/dependencies.md)                                                                                  |
| DataStore (preferences, typed), Room vs DataStore rules                                                        | [architecture.md](references/architecture.md#datastore-preferences--typed)                                                                                                                                     |
| Code formatting (Spotless, `spotlessCheck` / `spotlessApply`)                                                  | [assets/convention/QUICK_REFERENCE.md](assets/convention/QUICK_REFERENCE.md#spotless-plugin); [gradle-setup.md](references/gradle-setup.md)                                                                   |
| Compose patterns, motion, animation, modifiers, stability                                                      | [compose-patterns-quick.md](references/compose-patterns-quick.md)                                                                                                                                             |
| Paging 3 + Room + network (`RemoteMediator`, remote keys, `initialize`)                                        | [compose-patterns.md](references/compose-patterns.md#offline-first-paging-and-remotemediator)                                                                                                                 |
| Accessibility, TalkBack, label copy, live regions, Espresso a11y                                               | [android-accessibility-quick.md](references/android-accessibility-quick.md)                                                                                                                                   |
| Notifications, foreground services, MediaStyle, PiP, sharesheet                                                | [android-notifications.md](references/android-notifications.md)                                                                                                                                               |
| Media: API 37 background playback, Media3, picking, FileProvider, sharesheet                                   | [android-media.md](references/android-media.md)                                                                                                                                                               |
| Data sync and offline-first patterns                                                                           | [android-data-sync-quick.md](references/android-data-sync-quick.md)                                                                                                                                           |
| Material 3 theming, spacing tokens, dynamic colors                                                             | [android-theming-quick.md](references/android-theming-quick.md)                                                                                                                                               |
| Navigation3, deep links, App Links, adaptive layouts                                                           | [android-navigation-quick.md](references/android-navigation-quick.md)                                                                                                                                         |
| Kotlin patterns, View lifecycle interop                                                                        | [kotlin-patterns.md](references/kotlin-patterns.md)                                                                                                                                                           |
| Coroutine patterns (`StateFlow`, `Channel`, `callbackFlow`)                                                    | [coroutines-patterns-quick.md](references/coroutines-patterns-quick.md)                                                                                                                                       |
| Gradle, product flavors, BuildConfig, build performance, R8                                                    | [gradle-setup.md](references/gradle-setup.md)                                                                                                                                                                 |
| Code quality (Detekt convention plugin, CI)                                                                    | [code-quality.md](references/code-quality.md)                                                                                                                                                                 |
| Testing approach (unit, instrumented, Compose UI)                                                              | [testing-quick.md](references/testing-quick.md)                                                                                                                                                               |
| Internationalization and localization                                                                          | [android-i18n.md](references/android-i18n.md)                                                                                                                                                                 |
| Runtime permissions, Photo Picker, API 37 location privacy                                                     | [android-permissions.md](references/android-permissions.md)                                                                                                                                                   |
| Kotlin delegation patterns                                                                                     | [kotlin-delegation.md](references/kotlin-delegation.md)                                                                                                                                                       |
| Crash reporting (Firebase / Sentry interfaces, PII scrubbing)                                                  | [crashlytics.md](references/crashlytics.md)                                                                                                                                                                   |
| Design patterns (GoF-style, Room FTS)                                                                          | [design-patterns-quick.md](references/design-patterns-quick.md)                                                                                                                                               |
| Performance, Play Vitals, startup, recomposition, jank, APA, Perfetto                                          | [android-performance.md](references/android-performance.md)                                                                                                                                                   |
| Android 17 QPR2 memory budgets on constrained devices (optional)                                              | [android-performance.md](references/android-performance.md#android-17-qpr2-memory-budgets-optional)                                                                                                            |
| Debugging, Logcat, ANR, Gradle errors, R8 mapping, memory leaks                                                | [android-debugging.md](references/android-debugging.md)                                                                                                                                                       |
| Migrations (XML, RxJava, Navigation, Compose, Room 2→3, API 37, 16 KB native, Compose-XML interop)             | [migration.md](references/migration.md); [16 KB page size](references/migration.md#16-kb-memory-page-size-play-and-native-code); [Compose-XML interop](references/migration.md#compose-xml-interop-hardening) |

## Examples

**Greenfield Android app with convention plugins**

User goal: new repo matching the skill stack.

Actions: copy `assets/settings.gradle.kts.template`, `assets/libs.versions.toml.template`, `assets/convention/` into `build-logic/` per `assets/convention/QUICK_REFERENCE.md`; wire `includeBuild("build-logic")`; read [modularization.md](references/modularization.md) and [gradle-setup.md](references/gradle-setup.md).

Result: root + `app` + core modules with version catalog and convention plugins applied.

**New feature screen (Compose + ViewModel)**

User goal: one new flow in a feature module.

Actions: [modularization.md](references/modularization.md) for module naming and dependency direction; [compose-patterns-quick.md](references/compose-patterns-quick.md) for Screen, state, effects; [kotlin-patterns.md](references/kotlin-patterns.md) + [coroutines-patterns-quick.md](references/coroutines-patterns-quick.md) for `StateFlow` / events; [architecture.md](references/architecture.md) for domain vs data boundaries.

Result: feature module with Screen composable, ViewModel, `UiState`, and DI aligned to existing graphs.

**Offline-first list with Room 3 and remote API**

User goal: cached list + network refresh.

Actions: [compose-patterns.md](references/compose-patterns.md#offline-first-paging-and-remotemediator) for Paging 3 + `RemoteMediator`; [architecture.md](references/architecture.md) for repository placement; Room 3 + `SQLiteDriver` per [workflows.md](references/workflows.md) (Working with databases) and [migration.md](references/migration.md#room-2x-to-room-3) if upgrading.

Result: single source of truth in Room, UI driven by `PagingData` or equivalent pattern from the guide.

**Target SDK / compile SDK bump (e.g. API 37)**

User goal: migrate toolchain and platform requirements.

Actions: walk [migration.md](references/migration.md#android-17-api-37-migration); pin AGP/Kotlin/KSP using [gradle-setup.md](references/gradle-setup.md) and [dependencies.md](references/dependencies.md); cross-check edge-to-edge, media, security per [workflows.md](references/workflows.md) (Migrating to target SDK 37).

Result: `compileSdk` / `targetSdk` raised with manifest, Gradle, and feature code adjusted per the migration doc.

## Troubleshooting

| Symptom                                                              | Likely cause                                                                   | Fix                                                                                                                                                                                              |
|----------------------------------------------------------------------|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Gradle sync fails, plugin not found, or version catalog errors       | Missing `google()` / `mavenCentral()`, wrong plugin id, or catalog alias drift | [gradle-setup.md](references/gradle-setup.md); align with `assets/libs.versions.toml.template` when bootstrapping                                                                                |
| KSP errors on Room, or Room 3 builder rejects missing driver         | Room 3 (template `3.0.3`) expects `setDriver(BundledSQLiteDriver())` (or project equivalent) | [migration.md](references/migration.md#room-2x-to-room-3); [modularization.md](references/modularization.md); [architecture.md](references/architecture.md)                            |
| Unresolved `@TypeConverter`, or a DAO return type is rejected         | Room 3 renamed it to `@ColumnTypeConverter`; non-`Flow`/`suspend` return types need `@DaoReturnTypeConverters` | [migration.md](references/migration.md#dao-return-type-converters)                                              |
| Release-only crash while the class **is** listed in `seeds.txt`       | AGP 9 `strictFullModeForKeepRules`: `-keep class A` no longer keeps its constructor | [android-debugging.md](references/android-debugging.md#r8-keep-rules-troubleshooting); [gradle-setup.md](references/gradle-setup.md#agp-9-r8-defaults-that-change-existing-behavior)         |
| Gradle sync fails right after bumping Compose, nav3, or androidx.hilt | Those libraries compile against `compileSdk` 37 and require **AGP >= 9.2.0**    | [migration.md](references/migration.md#libraries-that-force-the-agp-floor); [gradle-setup.md](references/gradle-setup.md#agp-requires-a-minimum-gradle-wrapper)                                  |
| LAN device discovery or a local HTTP call silently fails at target 37 | `ACCESS_LOCAL_NETWORK` is required, or use the permissionless `NsdManager` picker | [android-permissions.md](references/android-permissions.md#local-network-access-api-37); [migration.md](references/migration.md#local-network-access-target-sdk-37)                             |
| Background audio is silent with no exception                         | API 37 audio hardening - no `MediaSession`, or no `mediaPlayback` FGS           | [android-media.md](references/android-media.md#diagnosing-silent-audio-failures)                                                                                                                 |
| Compose runtime warnings about unstable / skippable recompositions   | Unstable parameter types or state held incorrectly                             | [compose-patterns-quick.md](references/compose-patterns-quick.md); [android-performance.md](references/android-performance.md); [kotlin-patterns.md](references/kotlin-patterns.md)              |
| Release build crashes, `ClassNotFoundException`, or missing R8 rules | Shrinking removed reflective or JNI entry points                               | [android-debugging.md](references/android-debugging.md#r8-keep-rules-troubleshooting); [gradle-setup.md](references/gradle-setup.md#r8-keep-rules-audit)                                         |
| ANR or jank claims without evidence                                  | Main-thread or measurement assumptions                                         | [android-performance.md](references/android-performance.md#android-performance-analyzer-apa) or [Perfetto](references/android-performance.md#perfetto-system-traces) before architecture changes |