android-coroutines

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 4bc96bf96aac · 22 Oct 2026Report an issue or request a re-scan

• Publishernew-silvermoon GitHub userOwner of the repository this skill is read from
• Source foldernew-silvermoon/awesome-android-agent-skills/.github/skills/concurrency_and_networking/android-coroutinesThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict4bc96bf96aacA new audit runs when the source changes
• Repository statusNot archivedLast push 86 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Authoritative rules and patterns for production-quality Kotlin Coroutines onto Android. Covers structured concurrency, lifecycle integration, and reactive streams.

---
name: android-coroutines
description: Authoritative rules and patterns for production-quality Kotlin Coroutines onto Android. Covers structured concurrency, lifecycle integration, and reactive streams.
---

# Android Coroutines Expert Skill

This skill provides authoritative rules and patterns for writing production-quality Kotlin Coroutines code on Android. It enforces structured concurrency, lifecycle safety, and modern best practices (2025 standards).

## Responsibilities

*   **Asynchronous Logic**: Implementing suspend functions, Dispatcher management, and parallel execution.
*   **Reactive Streams**: Implementing `Flow`, `StateFlow`, `SharedFlow`, and `callbackFlow`.
*   **Lifecycle Integration**: Managing scopes (`viewModelScope`, `lifecycleScope`) and safe collection (`repeatOnLifecycle`).
*   **Error Handling**: Implementing `CoroutineExceptionHandler`, `SupervisorJob`, and proper `try-catch` hierarchies.
*   **Cancellability**: Ensuring long-running operations are cooperative using `ensureActive()`.
*   **Testing**: Setting up `TestDispatcher` and `runTest`.

## Applicability

Activate this skill when the user asks to:
*   "Fetch data from an API/Database."
*   "Perform background processing."
*   "Fix a memory leak" related to threads/tasks.
*   "Convert a listener/callback to Coroutines."
*   "Implement a ViewModel."
*   "Handle UI state updates."

## Critical Rules & Constraints

### 1. Dispatcher Injection (Testability)
*   **NEVER** hardcode Dispatchers (e.g., `Dispatchers.IO`, `Dispatchers.Default`) inside classes.
*   **ALWAYS** inject a `CoroutineDispatcher` via the constructor.
*   **DEFAULT** to `Dispatchers.IO` in the constructor argument for convenience, but allow it to be overridden.

```kotlin
// CORRECT
class UserRepository(
    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) { ... }

// INCORRECT
class UserRepository {
    fun getData() = withContext(Dispatchers.IO) { ... }
}
```

### 2. Main-Safety
*   All suspend functions defined in the Data or Domain layer must be **main-safe**.
*   **One-shot calls** should be exposed as `suspend` functions.
*   **Data changes** should be exposed as `Flow`.
*   The caller (ViewModel) should be able to call them from `Dispatchers.Main` without blocking the UI.
*   Use `withContext(dispatcher)` inside the repository implementation to move execution to the background.

### 3. Lifecycle-Aware Collection
*   **NEVER** collect a flow directly in `lifecycleScope.launch` or `launchWhenStarted` (deprecated/unsafe).
*   **ALWAYS** use `repeatOnLifecycle(Lifecycle.State.STARTED)` for collecting flows in Activities or Fragments.

```kotlin
// CORRECT
viewLifecycleOwner.lifecycleScope.launch {
    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState.collect { ... }
    }
}
```

### 4. ViewModel Scope Usage
*   Use `viewModelScope` for initiating coroutines in ViewModels.
*   Do not expose suspend functions from the ViewModel to the View. The ViewModel should expose `StateFlow` or `SharedFlow` that the View observes.

### 5. Mutable State Encapsulation
*   **NEVER** expose `MutableStateFlow` or `MutableSharedFlow` publicly.
*   Expose them as read-only `StateFlow` or `Flow` using `.asStateFlow()` or upcasting.

### 6. GlobalScope Prohibition
*   **NEVER** use `GlobalScope`. It breaks structured concurrency and leads to leaks.
*   If a task must survive the current scope, use an injected `applicationScope` (a custom scope tied to the Application lifecycle).

### 7. Exception Handling
*   **NEVER** catch `CancellationException` in a generic `catch (e: Exception)` block without rethrowing it.
*   Use `runCatching` only if you explicitly rethrow `CancellationException`.
*   Use `CoroutineExceptionHandler` only for top-level coroutines (inside `launch`). It has no effect inside `async` or child coroutines.

### 8. Cancellability
*   Coroutines feature **cooperative cancellation**. They don't stop immediately unless they check for cancellation.
*   **ALWAYS** call `ensureActive()` or `yield()` in tight loops (e.g., processing a large list, reading files) to check for cancellation.
*   Standard functions like `delay()` and `withContext()` are already cancellable.

### 9. Callback Conversion
*   Use `callbackFlow` to convert callback-based APIs to Flow.
*   **ALWAYS** use `awaitClose` at the end of the `callbackFlow` block to unregister listeners.

## Code Patterns

### Repository Pattern with Flow

```kotlin
class NewsRepository(
    private val remoteDataSource: NewsRemoteDataSource,
    private val externalScope: CoroutineScope, // For app-wide events
    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) {
    val newsUpdates: Flow<List<News>> = flow {
        val news = remoteDataSource.fetchLatestNews()
        emit(news)
    }.flowOn(ioDispatcher) // Upstream executes on IO
}
```

### Parallel Execution

```kotlin
suspend fun loadDashboardData() = coroutineScope {
    val userDeferred = async { userRepo.getUser() }
    val feedDeferred = async { feedRepo.getFeed() }
    
    // Wait for both
    DashboardData(
        user = userDeferred.await(),
        feed = feedDeferred.await()
    )
}
```

### Testing with runTest

```kotlin
@Test
fun testViewModel() = runTest {
    val testDispatcher = StandardTestDispatcher(testScheduler)
    val viewModel = MyViewModel(testDispatcher)
    
    viewModel.loadData()
    advanceUntilIdle() // Process coroutines
    
    assertEquals(expectedState, viewModel.uiState.value)
}
```

Excerpt, first 5,539 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/new-silvermoon/awesome-android-agent-skills
git -C awesome-android-agent-skills checkout 4bc96bf96aac

Works in

1. 2026-10-22
   ✓SAFE B 89 / 100

   first audit · source 4bc96bf96aac

Questions about android-coroutines

• github.com/new-silvermoon/awesome-android-agent-skills/tree/main — the audited source at commit 4bc96bf96aac and every finding aboveObserved · 22 Oct 2026

Spotted something wrong? Report a correction · Methodology