Kotlin Android Agent Skill

Native Android with Kotlin & Compose

You build production native Android: **Kotlin + Jetpack Compose + the UDF layered

architecture (UI → domain → data). One rule governs everything: state flows down,

events flow up, and there is exactly one source of truth per piece of state.** Get that

rule right and recomposition, rotation, and testing fall into place; break it and you get

a screen that compiles but recomposes every frame, leaks coroutine scopes, blocks the main

thread, or drops state on rotation.

This skill exists to stop the agent from reaching for the 2015 playbook — XML layouts,

findViewById, AsyncTask, LiveData inside Compose, GlobalScope.launch, MutableState

exposed straight out of a ViewModel. Emit a buildable, idiomatic module, not a toy.

Versions floor (2026)

These are floors verified against current docs (2026-06). Re-check the matrix before

locking — Compose and AGP move together and a mismatch fails the build.

| Piece | Floor | Why it matters |

|---|---|---|

| Kotlin (KGP) | 2.2.x | K2 compiler is default & Stable; KGP must align with AGP. |

| AGP | 9.2+ when using Compose | Compose's compileSdk 37 requires AGP ≥ 9.2.0. |

| compileSdk | 37 | Current Compose target. |

| minSdk | 24 | Practical modern floor (~99% devices); Compose technically supports 21+. |

| JDK (build) | 17 | Required by current AGP/Compose toolchain. |

| Compose BOM | 2026.05.01 → Compose 1.11.2 | Pin artifacts via the BOM, never per-artifact versions. |

| Navigation | 2.8+ | Type-safe @Serializable routes land here. |

| Hilt + Room + Retrofit | current | DI / persistence / network. Wire Room & Hilt with KSP, not kapt. |

| Serialization | kotlinx.serialization | Retrofit converter + Navigation route types. |

The architecture in one screen

Three layers. Higher layers depend on lower; never the reverse.

UI layer      Composable (stateless) ── reads ──> UiState
                     │ events up                  ▲ state down
              ViewModel exposes StateFlow<UiState> │
                     │ calls
domain layer  (optional) UseCase — only when logic spans repos or is reused
                     │ calls
data layer    Repository (interface in domain, impl here)
                  ├── Room DAO  → Flow   (single source of truth)
                  └── Retrofit  → suspend (refreshes the source of truth)

• UI is dumb: render UiState, send events. No business logic in a @Composable.
• domain is optional: add use-cases only when a screen needs logic from >1 repository.
• data owns truth: the repository decides; Room is the cache that the UI observes.

Offline-first means Room is the source of truth. The network writes into Room; the UI

observes Room's Flow. WorkManager does background sync. The UI never reads the network

directly.

State & recomposition

Each rule has a one-line reason.

• Hoist state. A composable that owns mutable state can't be reused or previewed — pass

state in, send events out.

• remember survives recomposition; rememberSaveable survives rotation/process death.

Use rememberSaveable for anything the user would be annoyed to lose (scroll, input).

• derivedStateOf for computed state — recomputes only when its inputs change, not every

recomposition.

• key() / stable keys in LazyColumn — without a stable item key, reorder/insert churns

the whole list.

• Business logic never lives in a @Composable — composables run on every recomposition.

// Bad — logic + I/O in the composable; runs on every recomposition.
@Composable
fun ArticlesScreen(repo: ArticleRepository) {
    val articles = runBlocking { repo.fetch() } // blocks UI thread, refetches constantly
    LazyColumn { items(articles) { Text(it.title) } }
}

// Good — stateless UI driven by hoisted state; logic in the ViewModel.
@Composable
fun ArticlesScreen(state: ArticlesUiState, onRetry: () -> Unit) {
    when (state) {
        ArticlesUiState.Loading -> CircularProgressIndicator()
        is ArticlesUiState.Error -> ErrorView(state.message, onRetry)
        is ArticlesUiState.Success ->
            LazyColumn { items(state.articles, key = { it.id }) { Text(it.title) } }
    }
}

ViewModel + UI state

Model the screen as a sealed UiState so impossible states (loading *and* error) can't

exist. Expose it as StateFlow, never a mutable type.

sealed interface ArticlesUiState {
    data object Loading : ArticlesUiState
    data class Success(val articles: List<Article>) : ArticlesUiState
    data class Error(val message: String) : ArticlesUiState
}

@HiltViewModel
class ArticlesViewModel @Inject constructor(
    repository: ArticleRepository,
) : ViewModel() {
    val uiState: StateFlow<ArticlesUiState> =
        repository.observeArticles()
            .map<List<Article>, ArticlesUiState> { ArticlesUiState.Success(it) }
            .catch { emit(ArticlesUiState.Error(it.message ?: "Unknown error")) }
            .stateIn(
                scope = viewModelScope,
                started = SharingStarted.WhileSubscribed(5_000),
                initialValue = ArticlesUiState.Loading,
            )
}

Collect it lifecycle-aware so collection pauses below STARTED and you don't burn work

off-screen:

@Composable
fun ArticlesRoute(viewModel: ArticlesViewModel = hiltViewModel()) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    ArticlesScreen(state = state, onRetry = viewModel::refresh)
}

WhileSubscribed(5_000) keeps the flow alive 5s past the last collector so a rotation

doesn't restart the upstream pipeline.

Data layer

The repository interface lives in domain; its implementation lives in data. Retrofit uses

suspend functions and a @Serializable DTO; Room DAOs return Flow. Errors surface as a

sealed result, not raw exceptions thrown into the UI.

interface ArticleRepository {
    fun observeArticles(): Flow<List<Article>>   // from Room — the source of truth
    suspend fun refresh()                         // network -> Room
}

The full wired example — DTO, entity, DAO, Retrofit service, repository impl, mappers,

offline-first refresh — is in references/architecture.md.

Read it before scaffolding a feature end-to-end.

DI with Hilt

@HiltAndroidApp on the Application, @Module @InstallIn(SingletonComponent::class) for

bindings, @HiltViewModel + hiltViewModel() for screens. Prefer constructor injection;

reach for @Provides/@Binds only for interfaces and third-party types you don't own.

Classic error: MyRepo cannot be provided without an @Inject constructor. Fix one of:

either add @Inject constructor(...) to the concrete class, or @Binds the interface to its

implementation inside an installed module. See references/gradle-setup.md

for the KSP wiring that makes Hilt generate.

Coroutines & Flow rules

• Never GlobalScope.launch — it outlives every screen and leaks. Use viewModelScope

(UI logic) or a repository-scoped scope.

• Structured concurrency: a cancelled parent cancels children — keep work inside a real

scope so navigation-away cancels it.

• Inject dispatchers (@IoDispatcher CoroutineDispatcher) instead of hardcoding

Dispatchers.IO — otherwise the work isn't testable.

• flowOn to switch a flow's upstream context, not withContext inside a flow { }

builder (which is a context-preservation violation).

• Cold Flow for streams, StateFlow for current-value state — don't collect a cold

flow when the UI needs the latest value.

Navigation (type-safe)

Since Navigation 2.8, routes are @Serializable types — the compiler checks your args.

@Serializable data object ArticleList
@Serializable data class ArticleDetail(val id: String)

NavHost(navController, startDestination = ArticleList) {
    composable<ArticleList> {
        ArticlesRoute(onOpen = { navController.navigate(ArticleDetail(it)) })
    }
    composable<ArticleDetail> { backStackEntry ->
        val args = backStackEntry.toRoute<ArticleDetail>()
        ArticleDetailRoute(id = args.id)
    }
}

No string routes, no manual arguments = listOf(navArgument(...)), no fragile key parsing.

Build & verify

./gradlew :app:assembleDebug lintDebug testDebugUnitTest

assembleDebug proves it builds, lintDebug catches Android lint, testDebugUnitTest runs

JVM unit tests. For a fast, SDK-free static gate over the Kotlin/Gradle you just wrote,

run scripts/verify.sh — it greps for banned patterns and missing modern ones without

touching the Android SDK, so it works in CI or a bare checkout.

Anti-patterns

| Anti-pattern | Why it bites | Do instead |

|---|---|---|

| XML layouts + findViewById | Stale; no compile-time view safety; doesn't compose | Jetpack Compose @Composable |

| LiveData collected in a Composable | Lifecycle mismatch, extra dependency, not Compose-native | StateFlow + collectAsStateWithLifecycle() |

| GlobalScope.launch | Leaks; outlives the screen; uncancellable | viewModelScope / scoped coroutine |

| runBlocking / network call on the main thread | ANR, frozen UI | suspend on an injected dispatcher |

| Business logic in a @Composable | Runs every recomposition; untestable | Move to ViewModel / use-case |

| MutableStateFlow/mutableStateOf exposed publicly | UI can mutate state; breaks single source of truth | private mutable backing + public asStateFlow()/StateFlow |

| God-Activity holding all state | Untestable, rotation-fragile | One ViewModel per screen, hoisted state |

| kapt for Room/Hilt | Slow, legacy; K2-incompatible edge cases | KSP |

| collectAsState() in Compose | Keeps collecting off-screen, wastes work | collectAsStateWithLifecycle() |

| Reading the network directly in the repository's read path | No offline; UI flickers on every fetch | Room as source of truth; network refreshes it |

When this is the wrong skill

• Shared UI across Android + iOS + desktop from one Kotlin codebase — the moment

commonMain, expect/actual, or an iOS target appears, use

../compose-multiplatform/SKILL.md.

• Server-side Kotlin / JVM web backend the app talks to → ../spring-boot/SKILL.md.
• Pure Kotlin/JVM language questions, no Android → ../java/SKILL.md is the

nearest JVM-language sibling (there is no standalone kotlin language skill).

• iOS/SwiftUI → swift-ios. Dart cross-platform → ../flutter/SKILL.md.

React Native → react-native.

• CI for assembleDebug/tests → github-actions.

References

• references/architecture.md — end-to-end wired feature

(UiState + ViewModel + Repository + Room + Retrofit + Hilt), complete file contents.

• references/gradle-setup.md — libs.versions.toml, root +

module build.gradle.kts, the Compose Kotlin plugin, Hilt/KSP wiring, and common

Gradle/build error fixes.