version: "1.0.1" name: kotlin-coroutines-skill description: "Expert guidance on Kotlin Coroutines and structured concurrency. Use when developers write or review async Kotlin code and need help ensuring correctness, safety, and testability of coroutine-based implementations." license: MIT metadata: version: "3.0.0"

Kotlin Coroutines

Overview

This skill provides expert guidance on Kotlin Coroutines, covering structured concurrency, scopes, Dispatchers (including main-safe suspend and dispatcher injection), cancellation (including withTimeout semantics), exception handling (CoroutineExceptionHandler, launch vs async), Channels, Flow (cold vs hot, collectLatest, SharedFlow configuration, blocking in flow {}), lifecycle-aware collection on Android, and testing (virtual time, setMain/resetMain). Use this skill to help developers write safe, maintainable concurrent code aligned with Kotlin 1.9+/2.0+ conventions and official best practices.

Agent Behavior Contract (Follow These Rules)

1. Identify the practice or error from the user's code or question (e.g. GlobalScope,

runBlocking in suspend, swallowing CancellationException) and open the corresponding reference from the Triage table in references/.

1. Apply the strict rules below in every response. Do not suggest or leave code that violates

them.

1. Respond in the required format: Analysis → Erroneous code → Optimized code → Explanation. If

the user only asks a conceptual question (no code), skip erroneous/optimized snippets and focus on analysis and explanation.

1. Do not recommend GlobalScope in production. Use framework scopes (viewModelScope,

lifecycleScope, rememberCoroutineScope), injected scopes, or local scopes ( coroutineScope { }, withContext { }). If an external scope is required, justify and document it.

1. Use async only when a return value is needed; if await() is never called, use launch.

Preserve structured concurrency: inside suspend functions use coroutineScope { } + async/ launch; do not launch in an external scope from suspend unless work must outlive the flow, and then document it.

1. Never use runBlocking inside suspend functions or coroutine-based code. Avoid ending a suspend

function with coroutineScope { launch { } } as the last line when the intent is fire-and-forget — coroutineScope waits for all children and blocks the caller; use an explicit external scope and document it if the work must truly run in the background beyond the caller's lifetime.

1. Use explicit Dispatchers: Dispatchers.Default for CPU-bound work, Dispatchers.Main/

Main.immediate for UI, withContext(Dispatchers.IO) for blocking I/O. Never perform blocking I/O on Default or Main. Do not use Dispatchers.Unconfined in production unless for a rare, documented case. Make suspend functions main-safe: move blocking work into withContext(Dispatchers.IO) so callers on Main are never blocked. Inject CoroutineDispatcher as a constructor parameter (default to real dispatcher; replace with TestDispatcher in tests).

1. Never pass Job() or SupervisorJob() directly to builders (e.g. launch(Job()) { }). Use

supervisorScope { } or a scope defined with SupervisorJob() for supervisor semantics. When running independent tasks with awaitAll, use supervisorScope instead of coroutineScope so one failure does not cancel sibling deferreds.

1. Cancellation handling (apply all):

• Never swallow CancellationException; rethrow it in catch blocks.
• Do not use CancellationException for domain errors; use normal exceptions instead.
• In long loops and repeating/polling work, add yield(), ensureActive(), or while (isActive)

with delay(interval) so the coroutine responds to cancellation.

• For suspend calls in finally, use withContext(NonCancellable) { }.
• Do not reuse a scope after scope.cancel(); use coroutineContext.job.cancelChildren() to

stop only children while keeping the scope alive.

• Prefer withTimeoutOrNull over withTimeout to avoid unintentionally cancelling the parent

scope. If using withTimeout, catch TimeoutCancellationException explicitly. Always ensure resources opened inside withTimeout are cleaned up in finally.

1. Exception handling:

• Uncaught exceptions in launch propagate to CoroutineExceptionHandler; in async, the

exception is stored in the Deferred and only thrown on await(). Always call await() on async blocks to avoid silently losing exceptions.

• Use CoroutineExceptionHandler at scope level for launch uncaught exceptions.

1. In tests use kotlinx-coroutines-test: runTest, virtual time, advanceTimeBy,

advanceUntilIdle, and inject TestDispatcher/StandardTestDispatcher; avoid real delay() with runBlocking. Replace Dispatchers.Main using Dispatchers.setMain(TestDispatcher()) in @Before and Dispatchers.resetMain() in @After.

1. Prefer produce { } for channels so they close when the coroutine ends. Do not share

consumeEach across multiple consumers; use for (x in channel) per consumer.

1. Flow best practices:

• Keep flow { } builder non-blocking; use flowOn(Dispatchers.IO) or suspend APIs.
• Use StateFlow for shared UI state (replays last value); use SharedFlow for events with

explicit replay, extraBufferCapacity, and onBufferOverflow configuration.

• Use collectLatest only when cancelling in-progress work is intentional (e.g. search); use

collect when each item must be processed to completion.

• On Android, collect flows with repeatOnLifecycle(Lifecycle.State.STARTED) or

flowWithLifecycle to stop collection when the UI goes to background.

1. When several practices apply (e.g. GlobalScope + wrong Dispatchers), use each relevant reference

and combine the fixes in one optimized snippet.

Recommended Tools for Analysis

When analyzing Kotlin projects for coroutine issues:

1. Project settings

• Use Read on build.gradle.kts / build.gradle for Kotlin version, kotlinx-coroutines-*

dependencies, and kotlinx-coroutines-test.

• Use Grep for CoroutineScope, GlobalScope, runBlocking, Dispatchers,

viewModelScope, lifecycleScope to locate usage patterns.

1. Scope and lifecycle

• Identify whether code runs on Android (viewModelScope, lifecycleScope), KMP, or plain JVM to

recommend the right scope.

Triage-First Playbook (Topic / Error → Reference)

Each references/ref-*.md file is self-contained (Bad Practice, Recommended, Why, Quick fix). Open the linked file directly — no dependency on repo docs when the skill is installed standalone.

Core Patterns Reference

When to Use Each Coroutine Tool

launch – Fire-and-forget or UI-triggered work that does not return a value

// Use for: Work that does not need a result; lifecycle-bound to scope
viewModelScope.launch {
    updateUI(loadData())
}

async / await – Parallel work when you need a return value

// Use for: Deferred result; always await (or awaitAll) to preserve structure
coroutineScope {
    val a = async { fetchA() }
    val b = async { fetchB() }
    combine(a.await(), b.await())
}

coroutineScope – Structured child work inside a suspend function

// Use for: Subtasks that must complete or cancel with the current scope
suspend fun loadAll() = coroutineScope {
    val one = async { loadOne() }
    val two = async { loadTwo() }
    Pair(one.await(), two.await())
}

withContext – Switch dispatcher or run cleanup (e.g. NonCancellable)

// Use for: Blocking I/O off Main/Default; cleanup in finally
withContext(Dispatchers.IO) { readFile(path) }
withContext(NonCancellable) { db.close() }

supervisorScope – Children do not cancel each other on failure

// Use for: Independent child jobs (e.g. multiple UI updates)
supervisorScope {
    launch { updateA() }
    launch { updateB() }
}

produce – Channel that closes when the coroutine ends

// Use for: Single producer; automatic close when scope completes
fun CoroutineScope.flowFromApi() = produce {
    for (item in api.stream()) send(item)
}

Common Scenarios

Scenario: Single network request with UI update

viewModelScope.launch {
    val data = withContext(Dispatchers.IO) { repo.fetch() }
    updateUI(data)
}

Scenario: Multiple parallel requests

coroutineScope {
    val users = async { repo.getUsers() }
    val posts = async { repo.getPosts() }
    show(users.await(), posts.await())
}

Scenario: Cancellation-friendly loop

for (i in list) {
    yield() // or ensureActive()
    process(i)
}

Best Practices Summary

1. Prefer structured concurrency – Use coroutineScope + async/launch inside suspend; avoid

launching in external scope from suspend unless documented. For independent tasks, use supervisorScope + awaitAll so one failure does not cancel siblings.

1. Use the right scope – Framework scopes (viewModelScope, lifecycleScope) or injected scope;

never GlobalScope in production.

1. Use async only when you need a result – Otherwise use launch. Always call await() on

every Deferred; exceptions are only thrown at await(), not caught by CoroutineExceptionHandler.

1. Use explicit, injected Dispatchers – IO for blocking I/O, Default for CPU, Main for UI; never

block on Default/Main. Make suspend functions main-safe (withContext(IO) internally). Inject dispatchers for testability.

1. Respect cancellation – Rethrow CancellationException; use while(isActive) + delay for

repeating work; use yield/ensureActive in long loops; use withContext(NonCancellable) for suspend cleanup in finally. Prefer withTimeoutOrNull; ensure resources are cleaned up on timeout.

1. Do not misuse CancellationException – Use normal exceptions for domain errors.
2. Test with virtual time – runTest, TestDispatcher, advanceTimeBy; avoid real delay()

in tests. Replace Dispatchers.Main with setMain/resetMain for reliable CI tests.

1. Channels – Prefer produce; if using Channel manually, document when close() is called;

one consumer per channel with for (x in channel).

1. Flow – Keep flow { } non-blocking (use flowOn); use StateFlow for state, SharedFlow

for events with explicit buffer/overflow config; use collectLatest only when cancelling in-progress work is intentional.

1. Android lifecycle – Collect flows with repeatOnLifecycle(STARTED) or flowWithLifecycle

so collection stops when UI is in background.

Output Format (Required for Code Review / Refactor)

Structure every code-review or refactor response as:

1. Problem Analysis – Short description of what is wrong (e.g. scope lifetime, dispatcher,

exception handling) and the risk (leaks, ANRs, flaky tests).

1. Erroneous Code – The original or problematic code snippet (clearly labeled).
2. Optimized Code – Refactored code that follows the guidelines (structured concurrency,

correct scopes, Dispatchers, exception/cancellation handling).

1. Technical Explanation – Why the optimized version is safer or more correct: lifecycle,

cancellation propagation, thread usage, testability.

For conceptual-only questions, skip erroneous/optimized snippets and keep analysis and explanation.

Verification Checklist (When You Change Coroutine Code)

• Confirm which scope is in use (framework, injected, or local) and that it matches lifecycle

expectations.

• After refactors: run tests, especially those that use coroutines or virtual time (see ref-6-*).
• If touching cancellation or cleanup: ensure CancellationException is rethrown and suspend cleanup

uses NonCancellable where needed.

• If touching Dispatchers: ensure no blocking I/O on Default or Main.