How to use the Wear OS Compose Material 3 Guide agent skill

What the wear-compose-m3 skill makes the agent do

An agent skill is a folder of instructions that an AI coding agent reads when a task matches the skill's description. This one covers creating, updating and migrating Wear OS projects that use the androidx.wear.compose.material3, androidx.wear.compose.foundation and androidx.wear.compose.navigation3 libraries, along with ambient mode and previews.

When the skill applies, the agent reads your gradle/libs.versions.toml or build.gradle.kts to find the library version already in use. It then works toward the latest stable version of Compose Material 3 for Wear, and it prefers current components such as AppScaffold, ScreenScaffold and TransformingLazyColumn over older Horologist or Material 2.5 equivalents.

• Migrates Horologist and Material 2.5 components to Material 3 equivalents, using the official migration guide the skill references.
• Checks parameter names, slot types and design tokens before refactoring a component.
• Consults canonical sample files for components such as buttons, dialogs, cards, pagers and ambient mode.
• Runs a Gradle sync and an assembleDebug build to check its changes, according to the skill's gotchas section.

Install the skill by downloading the ZIP

Download the ZIP for the wear-compose-m3 skill from this page, then unzip it. The skill's folder must contain SKILL.md, which is the file the agent reads first, along with its references folder.

You can install it in one of two places. For all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: ~/.claude/skills/ (available across projects).
• Project install: .claude/skills/ inside your project (shared with anyone who works in that repository).
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

Check your project before you ask for changes

The skill assumes a Gradle-based Android project, which you can open in Android Studio. Its prerequisites are Kotlin at the minimum version the skill lists, with the org.jetbrains.kotlin.plugin.compose Gradle plugin, and a minSdk of at least 25.

Compile SDK and the Android Gradle Plugin (AGP) must also meet the library's floors. The skill sets different floors for the 1.6.x and 1.7.x library lines, so check the SKILL.md file for the exact numbers rather than relying on memory. The agent is told not to run ./gradlew dependencies to resolve versions, so reading your build files directly is the expected approach.

• Android Studio or another Gradle-based Android project.
• Kotlin with the Compose compiler Gradle plugin.
• minSdk of at least 25.
• compileSdk and AGP at or above the floors listed in SKILL.md for your chosen library line.
• Network access to Google's Maven metadata, only if no internal version tool is available to the agent.

Ask for Wear OS work in plain language

You do not need special syntax. The skill's description covers creating, updating and migrating Wear projects, so a request that names Wear OS, Compose, Material 3, or a component such as TransformingLazyColumn will normally let the agent load it. If the agent does not seem to use the skill, name it directly in your request.

Be specific about your goal. Say whether you are starting a new screen, upgrading a version, or moving from Horologist or Material 2.5. Mention any visual output you must keep, because the skill tells the agent to accept Material 3 defaults rather than match old screenshots.

• Create a new Wear OS settings screen with a TransformingLazyColumn and a ListHeader.
• Migrate this screen from ScalingLazyColumn and Chip to the Material 3 equivalents.
• Add ambient mode support to this watch face screen and show me the preview.
• Update the Wear Compose Material 3 library and tell me what breaks.

Understand what changes when you migrate

For migrations, the skill maps older components to current ones. For example, ScalingLazyColumn becomes TransformingLazyColumn, Chip becomes Button, Confirmation becomes ConfirmationDialog, and PagerScreen becomes HorizontalPagerScaffold. The skill tells the agent not to use Horologist, Compose Layout or Compose Material libraries for these components.

Expect screenshot tests to fail after a migration. The skill says padding and positioning defaults have changed in Material 3, and that the agent should prefer those defaults rather than force the old look. If your product must keep exact older visuals, plan that work separately.

• ScalingLazyColumn → TransformingLazyColumn
• Chip → Button
• Confirmation → ConfirmationDialog
• PagerScreen → HorizontalPagerScaffold
• ResponsiveListHeader → ListHeader

Use the bundled component samples

The skill includes a reference table that links each Wear Compose component to a canonical sample. Included sample files cover areas such as AlertDialogSample, ButtonSample, ButtonGroupSample, CardSample, CheckboxButtonSample, AnimatedTextSample, TransformingLazyColumnSample and several foundation samples including AmbientModeSample, CurvedWorldSample, ExpandableSample, PagerSamples, RotarySamples and SwipeToDismissBoxSample.

Symbols marked [alpha], [beta] or [rc] are pre-release only. The skill tells the agent not to use them unless your project explicitly targets that pre-release track.

Review the safety notes before use

The skill does not run scripts. It does use the network in one case: if the agent has no internal tool to look up the latest stable library version, it may fetch Google's official Maven metadata XML to find that version. Review the agent's actions as you would any tool that edits your build files.

The skill also tells the agent not to downgrade the library because of an Unresolved reference error after a successful sync. Treat that as a guardrail, and check the reported error yourself, since the cause may be elsewhere in your code.

• Runs scripts: no.
• Uses network: yes, only for version lookup when no internal version tool exists.
• It edits build files such as libs.versions.toml and build.gradle.kts, so keep your project under version control.