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 - 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 |