macsystems

Kotlin Coroutine Exception Handling

Development community

SOURCE https://github.com/macsystems/kotlin-coroutine-exception-handling

Description

Agent skill for exception handling in Kotlin coroutines & Flow — structured concurrency, CancellationException safety, Flow error operators, retry with backoff, ViewModel/Repository/WorkManager patterns

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

README

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