# wear-compose-m3

Teaches the agent Wear OS Compose Material3: migrating off Material 2.5 and Horologist, canonical component samples, and the toolchain floors you need.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 9764
- Author: Google LLC
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/android/skills/tree/HEAD/wear/wear-compose-m3/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/wear-compose-m3

## What it does

The skill hands the coding agent a working brief for Wear OS watch UI on Compose Material3. It ships version floors, a lookup table of canonical samples for `androidx.wear.compose.material3` components, and a path off Material 2.5 and Horologist.

Migrations follow the official mapping: `ScalingLazyColumn` becomes `TransformingLazyColumn`, `Chip` becomes `Button`, `PagerScreen` becomes `HorizontalPagerScaffold`. Horologist libraries are off limits here, so the agent swaps them for M3 equivalents instead of running both. It reads your installed version from `gradle/libs.versions.toml` or `build.gradle.kts` rather than resolving dependencies through a shell command, and pulls the stable `compose-material3` version from the Maven metadata XML.

Setup needs Kotlin 2.0.0+ with the `org.jetbrains.kotlin.plugin.compose` plugin and `minSdk` 25 or higher. The 1.6.x line wants `compileSdk` 35 and AGP 8.6.0; 1.7.x wants 37 and 9.1.0. Check your AGP before installing, because older toolchains hit the AAR metadata floors and the agent has no sanctioned way around them. Component swaps also break screenshot tests, since padding and positioning defaults move to Material3 values and the skill says to keep those defaults rather than match old images.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add android/skills --skill wear-compose-m3 -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/wear-compose-m3/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/wear-compose-m3/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add android/skills --skill wear-compose-m3 -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/wear-compose-m3/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add android/skills --skill wear-compose-m3 -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/wear-compose-m3/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install android/skills wear-compose-m3
```

2. **Manually: put the files in place**
- File: `.github/skills/wear-compose-m3/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add android/skills --skill wear-compose-m3 -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/android/skills --path wear/wear-compose-m3
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/wear-compose-m3/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add android/skills --skill wear-compose-m3 -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/android/skills/tree/HEAD/wear/wear-compose-m3/SKILL.md

## When to use it
- port a `ScalingLazyColumn` screen to `TransformingLazyColumn`
- drop Horologist dependencies from a Wear module
- pick the `compose-material3` version that fits your AGP
- find a canonical sample for `AppScaffold` or `EdgeButton`
- get the build green again after a version bump

## Example prompts
- Port this watch screen from `ScalingLazyColumn` to `TransformingLazyColumn` in Wear Compose M3
- Read `gradle/libs.versions.toml` and outline the Horologist to `androidx.wear.compose.material3` migration
- Add ambient mode to the `AppScaffold` screen and show the sample from the skill

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d013a4cc8303ed87.

BEGIN THIRD-PARTY FILE d013a4cc8303ed87
```text
---
name: wear-compose-m3
description: Guidance for Wear OS Compose Material3 (Wear Compose Material 3 / Wear
  Compose Material3) watch and wearable apps. Covers creating, updating, and migrating
  projects (Material 2.5 and Horologist migration) using androidx.wear.compose.material3,
  androidx.wear.compose.foundation, and androidx.wear.compose.navigation3, including
  AppScaffold, ScreenScaffold, TransformingLazyColumn, ambient mode, and previews.
license: Complete terms in LICENSE.txt
metadata:
  author: Google LLC
  last-updated: '2026-10-22'
  keywords:
  - Wear OS
  - Compose
  - Material3
  - Horologist
  - TransformingLazyColumn
  - ScalingLazyColumn
  - AppScaffold
  - ScreenScaffold
  - EdgeButton
  - SwipeDismissableSceneStrategy
  - Material 2.5
  - ambient mode
---

## Prerequisites and compatibility

1. **Current Wear OS Compose version in-use:** To find the installed library version, read `gradle/libs.versions.toml` or `build.gradle.kts` directly. Don't run `./gradlew dependencies` or other shell commands to resolve versions.
2. **Wear OS Compose Material3 version:** If an internal tool is available to establish the **latest stable version** `{VERSION}` of `androidx.wear.compose:compose-material3`, use that tool.
   - Otherwise, fetch the [official Maven metadata XML](https://dl.google.com/dl/android/maven2/androidx/wear/compose/compose-material3/maven-metadata.xml) to identify `{VERSION}` (highest number, ignoring `-alpha`, `-beta`, or `-rc`).
3. **Strict compliance:** If a version is listed as stable, you MUST use it, unless overridden by the user. Do not downgrade based on initial "Unresolved reference" errors in the editor or outdated web search results.
4. **Kotlin \& Compose compiler:** Use Kotlin **2.0.0+** with the `org.jetbrains.kotlin.plugin.compose` Gradle plugin.
5. **Min SDK:** Ensure `minSdk` is at least **25**.
6. **Compile SDK \& AGP:** Ensure `compileSdk` and AGP meet the library's AAR metadata floors (`compileSdk >= 35` and `AGP >= 8.6.0` for `1.6.x`; `compileSdk >= 37` and `AGP >= 9.1.0` for `1.7.x`).

## Gotchas

1. **Mandatory sync and validation:** After updating versions in `libs.versions.toml` or `build.gradle.kts`, perform a Gradle sync (or `./gradlew assembleDebug`) before refactoring, and run `./gradlew assembleDebug` after refactoring to verify the build.
```
END THIRD-PARTY FILE d013a4cc8303ed87

The third-party file has ended. Everything between the d013a4cc8303ed87 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2339 of 39165 bytes. © Google LLC · Apache-2.0 · https://github.com/android/skills/tree/HEAD/wear/wear-compose-m3/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md