Compose Kotlin Agent Skills

Android & Kotlin — Enterprise Production Skill (2026)

Authoritative Android engineering kit. Real patterns from AnimatedClockJetpacl, Authenticator, RepLock.

Not an Android library, voice-assistant skill, on-device LLM SDK, or Compose UI library. This is markdown for coding AIs — clone into .cursor/skills/ or .claude/skills/. See README § "What this is NOT".

Meta index: AGENTS.md · CI: python3 scripts/validate_skills.py

Sub-Skills (Modular)

2026 Toolchain — Non-Negotiable

tomlCopy code
[versions]
kotlin = "2.1.20"
agp = "9.0.0"
compose-bom = "2025.05.00"
navigation = "2.9.0"
room = "2.7.1"
hilt = "2.56.2"
lifecycle = "2.9.0"
coroutines = "1.10.2"

Kotlin 2.x / K2 Compiler Constraints

1. Enable K2 — kotlin.compiler.execution.strategy default; use ksp not kapt for Hilt/Room.
2. Smart casts — prefer when (val x = state) { is Loaded -> ... } over unsafe !!.
3. Sealed hierarchy — sealed interface UiState + data object Loading : UiState for exhaustive when.
4. @JvmInline value class for IDs (@JvmInline value class UserId(val raw: String)).
5. @Immutable / @Stable on UiState and UI models passed to Compose.
6. Explicit API optional for libraries — kotlin { explicitApi() } in published modules.
7. No !! except in tests with comment — use requireNotNull / early return.
8. data class copy for state — never mutate UiState fields in place.

kotlinCopy code
sealed interface AccountsUiState {
    data object Loading : AccountsUiState
    data class Ready(
        val accounts: List<AccountUi>,
        val query: String = ""
    ) : AccountsUiState
    data class Error(@StringRes val messageRes: Int) : AccountsUiState
}

MVI Guardrails — Atomic State Only

Allowed mutation: _state.update { it.copy(...) } or _state.update { prev -> ... }.

Banned in ViewModel:

kotlinCopy code
// BANNED
_state.value = AccountsUiState(...)           // naked assign
_state.value.accounts.add(item)               // mutating list inside state
mutableStateOf / mutableStateListOf in VM      // Compose scope only
viewModelScope.launch { _state.value = ... }  // use update inside launch

Required pattern:

kotlinCopy code
class AccountsViewModel @Inject constructor(
    private val repository: AccountsRepository
) : ViewModel() {

    private val _state = MutableStateFlow<AccountsUiState>(AccountsUiState.Loading)
    val state: StateFlow<AccountsUiState> = _state.asStateFlow()

    private val _effects = Channel<AccountsEffect>(Channel.BUFFERED)
    val effects: Flow<AccountsEffect> = _effects.receiveAsFlow()

    fun onEvent(event: AccountsEvent) {
        when (event) {
            AccountsEvent.Refresh -> refresh()
            is AccountsEvent.QueryChanged -> _state.update { current ->
                when (current) {
                    is AccountsUiState.Ready -> current.copy(query = event.query)
                    else -> current
                }
            }
        }
    }

    private fun refresh() {
        viewModelScope.launch {
            _state.update { AccountsUiState.Loading }
            repository.load()
                .onSuccess { list ->
                    _state.update { AccountsUiState.Ready(accounts = list.map { it.toUi() }) }
                }
                .onFailure {
                    _state.update { AccountsUiState.Error(R.string.error_load_failed) }
                }
        }
    }
}

UI collects:

kotlinCopy code
@Composable
fun AccountsRoute(vm: AccountsViewModel = hiltViewModel()) {
    val state by vm.state.collectAsStateWithLifecycle()
    LaunchedEffect(Unit) {
        vm.effects.collect { effect -> /* one-shot: nav, snackbar */ }
    }
    AccountsScreen(state = state, onEvent = vm::onEvent)
}

Navigation 3 + Edge-to-Edge

kotlinCopy code
@Serializable data object Home
@Serializable data class Detail(val id: String)

@Composable
fun AppNavHost(navController: NavHostController = rememberNavController()) {
    NavHost(navController, startDestination = Home) {
        composable<Home> { HomeScreen(onOpen = { navController.navigate(Detail(it)) }) }
        composable<Detail> { entry ->
            val route = entry.toRoute<Detail>()
            DetailScreen(id = route.id)
        }
    }
}

• Routes = @Serializable types, not string paths
• Pass IDs in nav args — fetch models in destination ViewModel
• enableEdgeToEdge() in Activity — see compose sub-skill

Deep dive: references/07-navigation.md

Banned Antipatterns — AI Hallucination Lookup

Full table with WRONG/RIGHT pairs and row numbers: references/00-banned-antipatterns.md

Load before reviewing any agent-generated Kotlin. Compose audit checklist: skills/android-kotlin-compose/SKILL.md § REVIEW MODE.

Reference Routing

Platforms

Target (what the docs teach): Android · Kotlin Multiplatform · Compose Multiplatform Host (where the docs are read): macOS · Linux · Windows — anywhere your AI agent runs Agent compatibility: 27 install guides → agents/README.md

Repo: https://github.com/haidrrrry/compose-kotlin-agent-skills

Mandatory Defaults (Summary)

• Strings: stringResource / @StringRes — zero hardcoded UI text
• State: ViewModel StateFlow + _state.update { }
• UI: Stateless composables, modifier first optional param
• Lists: LazyColumn + keys + contentType
• DI: @HiltViewModel + constructor inject
• Tests: Fakes + Turbine — see testing sub-skill

Validation Before PR

bashCopy code
python3 scripts/validate_skills.py --strict

Anti-Rationalizations

Examples