Kotlin Coroutine Exception Handling — Development skill for Claude Code

kotlin-coroutine-exception-handling

An agent skill for handling failures correctly in Kotlin coroutines and Flow on Android. It teaches an AI coding agent (Claude Code, Gemini CLI, or anything else that reads [Agent Skills](https://agentskills.io)-style `SKILL.md` files) the failure semantics of structured concurrency, so generated and reviewed code gets the hard parts right:

• Where an exception actually surfaces — launch vs async, root vs child, coroutineScope vs supervisorScope, and why "async defers until await()" is only half true.
• CancellationException is not a failure — why catch (e: Exception) and runCatching around suspending calls are bugs, and the three safe patterns (including a runCatchingCancellable helper).
• CoroutineExceptionHandler as a safety net wired to crash reporting, not an error-handling strategy.
• Flow — catch transparency, why an exception inside collect {} bypasses upstream catch, and terminating errors before stateIn/shareIn.
• Retry with real exponential backoff — bounded, transient-only, jittered, and testable with virtual time.
• Layering — which layer catches what (Repository → domain error type, ViewModel → UI state, UI → renders state).

Contents

File	What it covers
SKILL.md	The core mental model, propagation table, scope shapes, cancellation safety, CoroutineExceptionHandler, Flow rules, backoff, layering, and a review checklist.
references/android-integration.md	Repository, ViewModel, lifecycle scopes and Compose, CoroutineWorker/WorkManager (Result.retry() with bounded attempts), app-scoped work.
references/testing.md	Testing failure paths with runTest, asserting cancellation is propagated (not swallowed), Turbine for Flow errors, backoff-curve assertions in virtual time.

Installation

Claude Code

Clone into your skills directory — per project:

git clone https://github.com/macsystems/ko