Android Kotlin Compose Development
Context ladder (smaller load first; full references stay complete):
- This file (
SKILL.md) - routing, stop rules, examples.
references/*-quick.md when listed below - required/forbidden + section links (~40 lines).- One target section in the full
references/*.md - code samples and checklists only.
- INDEX-sections.md - anchor dump only when quick routing is insufficient.
Forbidden: load 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. Full file list: 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, modularization.md. Stack migrations: migration.md.
- Greenfield: 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.
Outside-repo stop rules (do not substitute repo edits): Play upload, tracks, rollout, versionCode - android-ci-cd.md; Play Integrity prerequisites (Console/Cloud setup) - android-security-quick.md; production adb install / pm clear - testing.md.
Quick Reference
Rare or niche topics not listed here are in INDEX.md (complete file list).
| Task |
Reference |
| Task not in table, greenfield bootstrap, multi-topic setup |
workflows.md |
| Full index of all reference files |
INDEX.md |
| Version catalog, pins, alpha policy, brownfield alignment |
dependencies.md |
| Adding or updating dependencies (catalog aliases) |
dependencies.md |
| Multi-module dependencies |
dependencies.md |
| Project structure and modules |
modularization.md |
| MVVM layers, repositories, DI |
architecture.md |
| Retrofit / OkHttp, NetworkModule, nullable DTOs, AuthInterceptor |
architecture.md; dependencies.md |
| DataStore (preferences, typed), Room vs DataStore rules |
architecture.md |
Code formatting (Spotless, spotlessCheck / spotlessApply) |
assets/convention/QUICK_REFERENCE.md; gradle-setup.md |
| Compose patterns, motion, animation, modifiers, stability |
compose-patterns-quick.md |
Paging 3 + Room + network (RemoteMediator, remote keys, initialize) |
compose-patterns.md |
| Accessibility, TalkBack, label copy, live regions, Espresso a11y |
android-accessibility-quick.md |
| Notifications, foreground services, MediaStyle, PiP, sharesheet |
android-notifications.md |
| Media: API 37 background playback, Media3, picking, FileProvider, sharesheet |
android-media.md |
| Data sync and offline-first patterns |
android-data-sync-quick.md |
| Material 3 theming, spacing tokens, dynamic colors |
android-theming-quick.md |
| Navigation3, deep links, App Links, adaptive layouts |
android-navigation-quick.md |
| Kotlin patterns, View lifecycle interop |
kotlin-patterns.md |
Coroutine patterns (StateFlow, Channel, callbackFlow) |
coroutines-patterns-quick.md |
| Gradle, product flavors, BuildConfig, build performance, R8 |
gradle-setup.md |
| Code quality (Detekt convention plugin, CI) |
code-quality.md |
| Testing approach (unit, instrumented, Compose UI) |
testing-quick.md |
| Internationalization and localization |
android-i18n.md |
| Runtime permissions, Photo Picker, API 37 location privacy |
android-permissions.md |
| Kotlin delegation patterns |
kotlin-delegation.md |
| Crash reporting (Firebase / Sentry interfaces, PII scrubbing) |
crashlytics.md |
| Design patterns (GoF-style, Room FTS) |
design-patterns-quick.md |
| Performance, Play Vitals, startup, recomposition, jank, APA, Perfetto |
android-performance.md |
| Debugging, Logcat, ANR, Gradle errors, R8 mapping, memory leaks |
android-debugging.md |
| Migrations (XML, RxJava, Navigation, Compose, Room 2→3, API 37, 16 KB native, Compose-XML interop) |
migration.md; 16 KB page size; Compose-XML interop |
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 and 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 for module naming and dependency direction; compose-patterns-quick.md for Screen, state, effects; kotlin-patterns.md + coroutines-patterns-quick.md for StateFlow / events; 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 for Paging 3 + RemoteMediator; architecture.md for repository placement; Room 3 + SQLiteDriver per workflows.md (Working with databases) and migration.md 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; pin AGP/Kotlin/KSP using gradle-setup.md and dependencies.md; cross-check edge-to-edge, media, security per 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; align with assets/libs.versions.toml.template when bootstrapping |
| KSP errors on Room, or Room 3 builder rejects missing driver |
Room 3 (stable 3.0.0) expects setDriver(BundledSQLiteDriver()) (or project equivalent) |
migration.md; modularization.md; 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 |
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; gradle-setup.md |
| 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; gradle-setup.md |
| 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; migration.md |
| Background audio is silent with no exception |
API 37 audio hardening - no MediaSession, or no mediaPlayback FGS |
android-media.md |
| Compose runtime warnings about unstable / skippable recompositions |
Unstable parameter types or state held incorrectly |
compose-patterns-quick.md; android-performance.md; kotlin-patterns.md |
Release build crashes, ClassNotFoundException, or missing R8 rules |
Shrinking removed reflective or JNI entry points |
android-debugging.md; gradle-setup.md |
| ANR or jank claims without evidence |
Main-thread or measurement assumptions |
android-performance.md or Perfetto before architecture changes |
1---2name: claude-android-ninja3description: 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.4license: Apache-2.05---6# Android Kotlin Compose Development
7
8**Context ladder (smaller load first; full references stay complete):**
9
101. This file (`SKILL.md`) - routing, stop rules, examples.
112. `references/*-quick.md` when listed below - required/forbidden + section links (~40 lines).
123. One target section in the full `references/*.md` - code samples and checklists only.
134. [INDEX-sections.md](references/INDEX-sections.md) - anchor dump only when quick routing is insufficient.
14
15Forbidden: 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.
16
17Route 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).
18
19**Required:**
20
21- **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).
22- **Greenfield:** [workflows.md](references/workflows.md) → "Creating a new project?"
23- 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).
24
25**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).
26
27## Quick Reference
28
29Rare or niche topics not listed here are in [INDEX.md](references/INDEX.md) (complete file list).
30
31| Task | Reference |
32|----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
33| Task not in table, greenfield bootstrap, multi-topic setup | [workflows.md](references/workflows.md) |
34| Full index of all reference files | [INDEX.md](references/INDEX.md) |
35| Version catalog, pins, alpha policy, brownfield alignment | [dependencies.md](references/dependencies.md#version-strategy) |
36| Adding or updating dependencies (catalog aliases) | [dependencies.md](references/dependencies.md) |
37| Multi-module dependencies | [dependencies.md](references/dependencies.md) |
38| Project structure and modules | [modularization.md](references/modularization.md) |
39| MVVM layers, repositories, DI | [architecture.md](references/architecture.md) |
40| Retrofit / OkHttp, NetworkModule, nullable DTOs, AuthInterceptor | [architecture.md](references/architecture.md#network-layer-setup-corenetwork); [dependencies.md](references/dependencies.md) |
41| DataStore (preferences, typed), Room vs DataStore rules | [architecture.md](references/architecture.md#datastore-preferences--typed) |
42| Code formatting (Spotless, `spotlessCheck` / `spotlessApply`) | [assets/convention/QUICK_REFERENCE.md](assets/convention/QUICK_REFERENCE.md#spotless-plugin); [gradle-setup.md](references/gradle-setup.md) |
43| Compose patterns, motion, animation, modifiers, stability | [compose-patterns-quick.md](references/compose-patterns-quick.md) |
44| Paging 3 + Room + network (`RemoteMediator`, remote keys, `initialize`) | [compose-patterns.md](references/compose-patterns.md#offline-first-paging-and-remotemediator) |
45| Accessibility, TalkBack, label copy, live regions, Espresso a11y | [android-accessibility-quick.md](references/android-accessibility-quick.md) |
46| Notifications, foreground services, MediaStyle, PiP, sharesheet | [android-notifications.md](references/android-notifications.md) |
47| Media: API 37 background playback, Media3, picking, FileProvider, sharesheet | [android-media.md](references/android-media.md) |
48| Data sync and offline-first patterns | [android-data-sync-quick.md](references/android-data-sync-quick.md) |
49| Material 3 theming, spacing tokens, dynamic colors | [android-theming-quick.md](references/android-theming-quick.md) |
50| Navigation3, deep links, App Links, adaptive layouts | [android-navigation-quick.md](references/android-navigation-quick.md) |
51| Kotlin patterns, View lifecycle interop | [kotlin-patterns.md](references/kotlin-patterns.md) |
52| Coroutine patterns (`StateFlow`, `Channel`, `callbackFlow`) | [coroutines-patterns-quick.md](references/coroutines-patterns-quick.md) |
53| Gradle, product flavors, BuildConfig, build performance, R8 | [gradle-setup.md](references/gradle-setup.md) |
54| Code quality (Detekt convention plugin, CI) | [code-quality.md](references/code-quality.md) |
55| Testing approach (unit, instrumented, Compose UI) | [testing-quick.md](references/testing-quick.md) |
56| Internationalization and localization | [android-i18n.md](references/android-i18n.md) |
57| Runtime permissions, Photo Picker, API 37 location privacy | [android-permissions.md](references/android-permissions.md) |
58| Kotlin delegation patterns | [kotlin-delegation.md](references/kotlin-delegation.md) |
59| Crash reporting (Firebase / Sentry interfaces, PII scrubbing) | [crashlytics.md](references/crashlytics.md) |
60| Design patterns (GoF-style, Room FTS) | [design-patterns-quick.md](references/design-patterns-quick.md) |
61| Performance, Play Vitals, startup, recomposition, jank, APA, Perfetto | [android-performance.md](references/android-performance.md) |
62| Debugging, Logcat, ANR, Gradle errors, R8 mapping, memory leaks | [android-debugging.md](references/android-debugging.md) |
63| 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) |
64
65## Examples
66
67**Greenfield Android app with convention plugins**
68
69User goal: new repo matching the skill stack.
70
71Actions: 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).
72
73Result: root + `app` + core modules with version catalog and convention plugins applied.
74
75**New feature screen (Compose + ViewModel)**
76
77User goal: one new flow in a feature module.
78
79Actions: [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.
80
81Result: feature module with Screen composable, ViewModel, `UiState`, and DI aligned to existing graphs.
82
83**Offline-first list with Room 3 and remote API**
84
85User goal: cached list + network refresh.
86
87Actions: [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.
88
89Result: single source of truth in Room, UI driven by `PagingData` or equivalent pattern from the guide.
90
91**Target SDK / compile SDK bump (e.g. API 37)**
92
93User goal: migrate toolchain and platform requirements.
94
95Actions: 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).
96
97Result: `compileSdk` / `targetSdk` raised with manifest, Gradle, and feature code adjusted per the migration doc.
98
99## Troubleshooting
100
101| Symptom | Likely cause | Fix |
102|----------------------------------------------------------------------|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
103| 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 |
104| KSP errors on Room, or Room 3 builder rejects missing driver | Room 3 (stable `3.0.0`) 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) |
105| 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) |
106| 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) |
107| 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) |
108| 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) |
109| 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) |
110| 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) |
111| 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) |
112| 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 |
drjacky