claude-android-ninja

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
Optional Android CLI project discovery, Studio checks, preview, and test-device inspection	workflows.md ("Using the optional Android CLI for agent workflows?")
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
Android 17 QPR2 memory budgets on constrained devices (optional)	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 (template 3.0.3) 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