CO

A guide for building shared Compose Multiplatform UI components, managing state, and optimizing performance across Android and Desktop platforms.

Install

mkdir -p .claude/skills/compose-expert && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/1754" && unzip -o skill.zip -d .claude/skills/compose-expert && rm skill.zip

Installs to .claude/skills/compose-expert

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Advanced Compose Multiplatform UI patterns for shared composables. Use when working with visual UI components, state management patterns (remember, derivedStateOf, produceState), recomposition optimization (@Stable/@Immutable visual usage), Material3 theming, custom ImageVector icons, or determining whether to share UI in commonMain vs keep platform-specific. Delegates navigation to android-expert/desktop-expert. Complements kotlin-expert (handles Kotlin language aspects of state/annotations).
498 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Advanced

Key capabilities

  • →Organizes shared UI code in commonMain
  • →Optimizes recomposition via stable/immutable annotations
  • →Implements cross-platform Material3 theming
  • →Generates ImageVector icons for shared use
  • →Structures state management for multiplatform apps

How it works

Applies a set of architectural rules for grouping UI logic and state handling into shared library modules.

Inputs & outputs

You give it
Compose UI component or state requirement
You get back
Shared UI code block or architectural pattern

When to use compose-expert

  • →Refactoring shared UI components into commonMain
  • →Optimizing recomposition with @Stable and @Immutable
  • →Building custom ImageVector icons
  • →Implementing Material3 theming for cross-platform apps

About this skill

compose-expert

Where shared Compose UI lives in Amethyst and the house rules for it. What goes in commons vs commonsUI vs a platform shim is in AGENTS.md ("Sharing Philosophy", "Feature Workflow") and commonsUI/ARCHITECTURE.md; this skill does not repeat it.

Delegate: Activity / manifest / flavors -> android-expert; Window, tray, menu bar -> desktop-expert; source-set placement, expect/actual, extracting an Android composable -> kotlin-multiplatform; feeds and Account state -> account-state; Flow and coroutine scopes -> kotlin-coroutines.

Where things live

All paths below are under commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/.

WhatWhere
Screensui/screen/loggedIn/<feature>/ (and ui/screen/ for shared feed views)
Reusable componentsui/components/ (catalog: references/shared-composables-catalog.md)
Feed scaffoldingui/feeds/ (RenderFeedContentState, RefresheableBox, FeedEmpty, LoadingFeed)
Note renderingui/note/ (NoteCompose), rich text in ui/richtext/ + ui/components/RichTextViewer.kt
Themeui/theme/ (AmethystColorScheme.kt palettes + ColorScheme.* tokens, ColorScheme.isLight, Shape.kt, Type.kt)
Window tiersui/layouts/ScreenLayout.kt (ScreenLayoutSpec, LocalScreenLayout, FeedContentMaxWidth)
Shell + navui/app/AmethystApp.kt, ui/app/AppRoot.kt, ui/navigation/ (see below)
Platform ports for UIui/platform/AppPlatform.kt (LocalAppPlatform), ui/components/PlatformPermission.kt
Iconsicons/ (Amethyst glyph font) and icons/symbols/ (MaterialSymbols, AmethystIcons)
Robohash avatarsrobohash/ (CachedRobohash, RobohashAssembler, parts/)
StringscommonsUI/src/commonMain/composeResources/values/strings.xml -> Res.string.* (rules: AGENTS.md "Strings")

The Android app's AmethystTheme wrapper is still in amethyst/src/main/java/com/vitorpamplona/amethyst/ui/theme/Theme.kt; the palettes it applies are shared.

The shell and window tiers

One shell for every window, chosen by size, not by platform (AGENTS.md "Navigation Shell"):

  • AmethystApp (ui/app/AmethystApp.kt) is the root both front ends call. Android's MainActivity passes AndroidAppRoot; the desktop window (AmethystDesktop.kt) passes a DesktopAppRoot. AppRoot (ui/app/AppRoot.kt) is the port each platform implements: createAccountViewModel, rememberScreenLayoutSpec, registerDestinations, ShellOverlay, NavigationEffects, ...
  • ScreenLayoutSpec.navigationStyle is BOTTOM_BAR, NAV_RAIL or PERMANENT_DRAWER; hasRoomForNotificationPanel docks the notification panel. isLargeScreen is "not the bottom bar". Read it with LocalScreenLayout.current, never with a platform check.
  • AppShellLayout (ui/navigation/shell/) lays out the bar / rail / drawer; ui/navigation/bottombars/ holds AppBottomBar and AppNavigationRail; ui/navigation/deck/DeckArea.kt adds the opt-in deck columns on windows of 1,200 dp+.

Navigation 3

The app owns its back stack as snapshot state; NavDisplay only renders it. No NavController, no graph. Full rules in references/navigation.md.

  • Routes: @Serializable sealed class Route in commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/model/navigation/Routes.kt. The back stack is saved through kotlinx-serialization, so every route argument must be serializable.
  • NavBackStacks (same package) holds the window's NavModel: StackModel (stack, never empty, starts at Route.Home; savedTabs, the root of each bottom-bar tab you left), TabsModel or WindowsModel. Every navigation is a NavRequest the model reads its own way. A NavStackEntry's contentKey is "nav-$id": saved state and ViewModels key on it, so the same route opened twice is two screens.
  • Nav (ui/navigation/navs/Nav.kt) implements INav: nav, navDrawer, newStack, navBottomBar, popBack, popUpTo, each after the keyboard settles (ImeSettler).
  • Register a screen once with a builder from ui/navigation/host/NavDestinations.kt. Shared screens go in NavDestinations.sharedDestinations (ui/navigation/host/SharedDestinations.kt); Android-only ones in androidDestinations in amethyst/src/main/java/com/vitorpamplona/amethyst/ui/navigation/AppNavigation.kt. The builder picks the motion and the reading-column cap:
// from SharedDestinations.kt
composableCapped<Route.Home> { HomeScreen(accountViewModel, nav) }
composable<Route.Message> { MessagesScreen(accountViewModel, nav) }
composableFromEnd<Route.Polls> { PollsScreen(accountViewModel, nav) }
composableFromEnd<Route.Browser>(capWidth = false) { BrowserScreen(accountViewModel, nav) }
composableFromBottomArgs<Route.AwardBadge> { AwardBadgeScreen(it.kind, it.pubKeyHex, it.dTag, accountViewModel, nav) }

A route nobody registered fails the first time it is opened (the desktop installs an unavailable screen instead). Gate a menu item on canOpen(route) when a front end may lack it.

Composable conventions that differ from the default

  • Strings come from Res, read with stringRes(Res.string.x); no literal user-visible text in a shared composable, no Android R.string. Default label parameters are StringResource (see AddButton in ui/components/ActionButtons.kt).
  • UI-state collections are kotlinx.collections.immutable (ImmutableList, ImmutableMap, persistentListOf), an api dependency of commonsUI. The parser output (RichTextViewerState, ParagraphState) and the platform ports already use them; pass those, not List, into composables.
  • @Immutable / @Stable mark the state classes and port interfaces handed to composables (ScreenLayoutSpec, AppPlatform, PlatformPermission). Only mark a class you can keep truly immutable.
  • Theme-dependent values come from the color scheme: MaterialTheme.colorScheme.isLight (memoized in AmethystColorScheme.kt), not a hand-rolled luminance check.
  • Icons follow AGENTS.md "Icons": icons/*.kt compile into amethyst_icons.ttf and draw through AmethystIconGlyph; Material icons are MaterialSymbols from a subset font, so a new codepoint needs tools/material-symbols-subset/subset.sh. Robohash is the one ImageVector-built asset: references/icon-assets.md.
  • Parse rich text through CachedRichTextParser, never per recomposition: references/rich-text-parsing.md.
  • Permissions in shared UI go through an expect fun rememberXPermission(): PlatformPermission (see ui/components/LocationPermission.kt; the Android actual wraps Accompanist).

Reviewing a component's public API

For slot parameters, modifier placement, and the other API-shape checks, use references/api-style.md.

Performance: measure first

Feed jank in this app has been measured as GC-bound and RenderThread-bound, with composition a small share of frame time. Stability annotations, derivedStateOf and deferred reads only help when a trace shows composition is the cost. Profile a release-like build (the benchmark build type in amethyst/build.gradle.kts is minified and profileable) before you apply them, and measure again afterwards.

Compose compiler reports are configured only for :amethyst (composeCompiler { reportsDestination ... } near line 551 of amethyst/build.gradle.kts, written to amethyst/build/compose_compiler/). They cover only composables compiled in that module. Shared composables are compiled in :commonsUI, which has no such block. To inspect their skippability, add the block to commonsUI/build.gradle.kts temporarily, and don't commit it.

See it running

A screen change is not done until you've looked at it: tools/desktop-run/run-headless.sh start runs the desktop app, which is this same UI, on a virtual display and screenshots it. AMETHYST_SCREEN=480x900x24 shows the phone tier. See tools/desktop-run/README.md and desktop-expert.

References

  • references/navigation.md: back-stack operations, rendering, transitions, intents, tests
  • references/shared-composables-catalog.md: the reusable components and their signatures
  • references/rich-text-parsing.md: RichTextParser, segments, CachedRichTextParser, NIP-92 imeta
  • references/icon-assets.md: robohash avatars
  • references/api-style.md: component API review checklist (slots, modifiers)

When not to use it

  • →Applications targeting a single platform exclusively
  • →UI logic tied heavily to platform-specific system APIs

Prerequisites

Kotlin Multiplatform SDKCompose Multiplatform dependency

Limitations

  • →Requires familiarity with KMP architectural constraints
  • →Material3 primitives must be strictly followed for sharing
  • →Debugging cross-platform state is complex

How it compares

It provides a clear framework for deciding when to share code, avoiding the common 'share-everything' approach that causes platform crashes.

Compared to similar skills

compose-expert side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
compose-expert (this skill)67moReviewAdvanced
android-kotlin77moNo flagsIntermediate
kotlin-expert55moNo flagsAdvanced
android-jetpack-compose-expert47moNo flagsAdvanced

Try saying

Example prompts that trigger this skill in your AI assistant.

More by vitorpamplona

View all by vitorpamplona →

kotlin-multiplatform

vitorpamplona

Platform abstraction decision-making for Amethyst KMP project. Guides when to abstract vs keep platform-specific, source set placement (commonMain, jvmAndroid, platform-specific), expect/actual patterns. Covers primary targets (Android, JVM/Desktop, iOS) with web/wasm future considerations. Integrates with gradle-expert for dependency issues. Triggers on: abstraction decisions ("should I share this?"), source set placement questions, expect/actual creation, build.gradle.kts work, incorrect placement detection, KMP dependency suggestions.

32156

kotlin-expert

vitorpamplona

Advanced Kotlin patterns for AmethystMultiplatform. Flow state management (StateFlow/SharedFlow), sealed hierarchies (classes vs interfaces), immutability (@Immutable, data classes), DSL builders (type-safe fluent APIs), inline functions (reified generics, performance). Use when working with: (1) State management patterns (StateFlow/SharedFlow/MutableStateFlow), (2) Sealed classes or sealed interfaces, (3) @Immutable annotations for Compose, (4) DSL builders with lambda receivers, (5) inline/reified functions, (6) Kotlin performance optimization. Complements kotlin-coroutines agent (async patterns) - this skill focuses on Amethyst-specific Kotlin idioms.

526

kotlin-coroutines

vitorpamplona

Advanced Kotlin coroutines patterns for AmethystMultiplatform. Use when working with: (1) Structured concurrency (supervisorScope, coroutineScope), (2) Advanced Flow operators (flatMapLatest, combine, merge, shareIn, stateIn), (3) Channels and callbackFlow, (4) Dispatcher management and context switching, (5) Exception handling (CoroutineExceptionHandler, SupervisorJob), (6) Testing async code (runTest, Turbine), (7) Nostr relay connection pools and subscriptions, (8) Backpressure handling in event streams. Delegates to kotlin-expert for basic StateFlow/SharedFlow patterns. Complements nostr-expert for relay communication.

311

nostr-expert

vitorpamplona

Nostr protocol implementation patterns in Quartz (AmethystMultiplatform's KMP Nostr library). Use when working with: (1) Nostr events (creating, parsing, signing), (2) Event kinds and tags, (3) NIP implementations (57 NIPs in quartz/), (4) Event builders and TagArrayBuilder DSL, (5) Nostr cryptography (secp256k1, NIP-44 encryption), (6) Relay communication patterns, (7) Bech32 encoding (npub, nsec, note, nevent). Complements nostr-protocol agent (NIP specs) - this skill provides Quartz codebase patterns and implementation details.

323

gradle-expert

vitorpamplona

Build optimization, dependency resolution, and multi-module KMP troubleshooting for AmethystMultiplatform. Use when working with: (1) Gradle build files (build.gradle.kts, settings.gradle), (2) Version catalog (libs.versions.toml), (3) Build errors and dependency conflicts, (4) Module dependencies and source sets, (5) Desktop packaging (DMG/MSI/DEB), (6) Build performance optimization, (7) Proguard/R8 configuration, (8) Common KMP + Android Gradle issues (Compose conflicts, secp256k1 JNI variants, source set problems).

19

You might also like

android-kotlin

alinaqi

Android Kotlin development with Coroutines, Jetpack Compose, Hilt, and MockK testing

729

kotlin-expert

vitorpamplona

Advanced Kotlin patterns for AmethystMultiplatform. Flow state management (StateFlow/SharedFlow), sealed hierarchies (classes vs interfaces), immutability (@Immutable, data classes), DSL builders (type-safe fluent APIs), inline functions (reified generics, performance). Use when working with: (1) State management patterns (StateFlow/SharedFlow/MutableStateFlow), (2) Sealed classes or sealed interfaces, (3) @Immutable annotations for Compose, (4) DSL builders with lambda receivers, (5) inline/reified functions, (6) Kotlin performance optimization. Complements kotlin-coroutines agent (async patterns) - this skill focuses on Amethyst-specific Kotlin idioms.

526

android-jetpack-compose-expert

sickn33

Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3.

413

reviewing-changes

bitwarden

Guides Android code reviews with type-specific checklists and MVVM/Compose pattern validation. Use when reviewing Android PRs, pull requests, diffs, or local changes involving Kotlin, ViewModel, Composable, Repository, or Gradle files. Triggered by "review PR", "review changes", "check this code", "Android review", or code review requests mentioning bitwarden/android. Loads specialized checklists for feature additions, bug fixes, UI refinements, refactoring, dependency updates, and infrastructure changes.

12

kmp-cmp-app-builder

firdaus1453

>

00

Android Navigation

li-lance

Standards for Jetpack Navigation Compose (Type-safe)

00

Search skills

Search the agent skills registry