compose-performance-skills

What this skill does

```markdown
---
name: compose-performance-skills
description: Install and use the skydoves/compose-performance-skills agent skill library to diagnose and fix Jetpack Compose performance issues including stability, recomposition, lazy layouts, modifiers, side effects, and build configuration.
triggers:
  - "my composable recomposes too often"
  - "LazyColumn drops frames during scroll"
  - "diagnose Compose stability issues"
  - "fix unnecessary recomposition in Jetpack Compose"
  - "optimize Compose performance"
  - "Compose unstable parameters compiler report"
  - "baseline profile for Compose app"
  - "install compose performance skills"
---

# Compose Performance Skills

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A curated library of Agent Skills (SKILL.md files) for Jetpack Compose performance. Each skill teaches an AI coding agent to diagnose and fix one specific Compose performance problem—stability, recomposition, lazy layouts, custom modifiers, side effects, baseline profiles, R8, and hot reload.

## What This Library Does

- **26 skills** organized into 9 categories: `stability`, `recomposition`, `lists`, `modifiers`, `side-effects`, `measurement`, `build`, `audit`, `hot-reload`
- Each `SKILL.md` is operational instructions for an LLM—terse, imperative, with RIGHT/WRONG code pairs and a verification checklist
- Skills chain together: a diagnostic skill names the fix skills it hands off to; a fix skill states which diagnostic skill produced its input
- Grounded in primary sources: Android Developers docs, Compose compiler internals, AndroidX release notes

## Installation

### Claude Code (Recommended)

```bash
# Clone to stable location
git clone https://github.com/skydoves/compose-performance-skills.git \
  ~/.claude/skills-sources/compose-performance-skills

# Run idempotent install script (symlinks each skill into ~/.claude/skills/<slug>/)
~/.claude/skills-sources/compose-performance-skills/scripts/install-skills.sh
```

Custom target directory:
```bash
./scripts/install-skills.sh /path/to/agent/skills
```

Uninstall:
```bash
./scripts/install-skills.sh --uninstall
```

Restart Claude Code after install. Mention a Compose performance symptom and Claude Code matches trigger vocabulary in skill frontmatter to load the relevant `SKILL.md` automatically.

### Android Studio Agent Mode / Gemini (Project-Local)

```bash
cd <your-android-project>

git clone https://github.com/skydoves/compose-performance-skills.git \
  .compose-performance-skills-source

./.compose-performance-skills-source/scripts/install-skills.sh .agent/skills
```

Add `.compose-performance-skills-source/` to `.gitignore`. Update skills with `git pull` inside the source directory.

### Claude.ai / Anthropic API

Upload individual `SKILL.md` files as Agent Skill attachments in a Claude.ai workspace, or inject them into the system prompt for direct API use. Skills are self-contained Markdown—no external runtime required.

## Directory Layout

```
compose-performance-skills/
├── README.md
├── INDEX.md                        # symptom → skill lookup table
├── scripts/
│   └── install-skills.sh
└── <category>/<slug>/
    ├── SKILL.md                    # the skill (required)
    └── references/
        └── <topic>.md              # supplemental material (one level deep)
```

**Categories and slugs:**

| Category | Key Skills |
|---|---|
| `stability/` | `diagnosing-compose-stability`, `stabilizing-compose-types`, `configuring-stability-config` |
| `recomposition/` | `deferring-state-reads`, `applying-derived-state-of`, `tracing-recomposition` |
| `lists/` | `optimizing-lazy-layouts`, `stable-keys-content-type`, `lazy-layout-prefetch` |
| `modifiers/` | `migrating-to-modifier-node`, `graphics-layer-animated-reads` |
| `side-effects/` | `collecting-flows-safely`, `memoizing-lambdas-strong-skipping` |
| `measurement/` | `running-macrobenchmark`, `generating-baseline-profiles` |
| `build/` | `enabling-r8-full-mode`, `enabling-strong-skipping`, `ci-stability-validation` |
| `audit/` | `end-to-end-performance-audit` |
| `hot-reload/` | `compose-hot-reload-hotswan` |

## Key Skill Workflows

### Diagnosing Stability (`stability/diagnosing-compose-stability/SKILL.md`)

Triggered by: "recomposition spike", "unstable parameters", "composable won't skip"

**What it does:**
1. Enables Compose Compiler reports in `release` build type
2. Parses `<module>-composables.txt` for `unstable` parameters
3. Chains to `stabilizing-compose-types` for the fix

```kotlin
// build.gradle.kts – enable compiler reports
android {
    buildTypes {
        release {
            // Compose compiler metrics output
        }
    }
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
    compilerOptions {
        freeCompilerArgs.addAll(
            "-P",
            "plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=" +
                layout.buildDirectory.dir("compose_metrics").get().asFile.absolutePath,
            "-P",
            "plugin:androidx.compose.compiler.plugins.kotlin:metricsDestination=" +
                layout.buildDirectory.dir("compose_metrics").get().asFile.absolutePath
        )
    }
}
```

Run the report:
```bash
./gradlew :app:assembleRelease
cat app/build/compose_metrics/app_release-composables.txt | grep "unstable"
```

### Stabilizing Compose Types (`stability/stabilizing-compose-types/SKILL.md`)

```kotlin
// WRONG – List<T> is unstable
@Composable
fun ItemList(items: List<Item>) { ... }

// RIGHT – use ImmutableList from kotlinx.collections.immutable
import kotlinx.collections.immutable.ImmutableList
import kotlinx.collections.immutable.persistentListOf

@Composable
fun ItemList(items: ImmutableList<Item>) { ... }

// In ViewModel
val items: StateFlow<ImmutableList<Item>> = _items.asStateFlow()
```

```kotlin
// WRONG – data class with unstable field
data class UiState(
    val items: List<Item>,          // unstable
    val callback: () -> Unit        // unstable
)

// RIGHT – @Stable annotation + immutable collections
@Stable
data class UiState(
    val items: ImmutableList<Item>,
    val onItemClick: (Item) -> Unit
)
```

### Deferring State Reads (`recomposition/deferring-state-reads/SKILL.md`)

```kotlin
// WRONG – offset read triggers recomposition of the entire composable
@Composable
fun AnimatedBox(scrollState: ScrollState) {
    val offset = scrollState.value  // read here = recompose entire function
    Box(Modifier.offset(y = offset.dp)) { ... }
}

// RIGHT – defer read into modifier lambda (layout phase only)
@Composable
fun AnimatedBox(scrollState: ScrollState) {
    Box(
        Modifier.offset {                    // read deferred to layout phase
            IntOffset(0, scrollState.value)
        }
    ) { ... }
}

// RIGHT – defer into graphicsLayer lambda (draw phase only)
@Composable
fun FadingBox(alpha: State<Float>) {
    Box(
        Modifier.graphicsLayer {             // read deferred to draw phase
            this.alpha = alpha.value
        }
    ) { ... }
}
```

### Optimizing Lazy Layouts (`lists/optimizing-lazy-layouts/SKILL.md`)

```kotlin
// WRONG – no keys, no contentType
LazyColumn {
    items(itemList) { item ->
        ItemCard(item)
    }
}

// RIGHT – stable keys + contentType
LazyColumn {
    items(
        items = itemList,
        key = { item -> item.id },              // stable, unique key
        contentType = { item -> item::class }   // group similar items
    ) { item ->
        ItemCard(item)
    }
}
```

```kotlin
// WRONG – lambda captures unstable reference
LazyColumn {
    items(items, key = { it.id }) { item ->
        ItemCard(
            item = item,
            onClick = { viewModel.onItemClick(item) }  // new lambda each recomposition
        )
    }
}

// RIGHT – hoist click handler, use rememberUpdatedState if needed
LazyColumn {
    items(items, key = { it.id }) { item ->
        ItemCard(
            item = item,
            onClick = remember(item.