README.md

May 3, 2026 · View on GitHub

Jetpack Compose logo

Compose Agent Skill

Make your AI coding tool actually understand Compose — Android, Desktop, iOS, and Web.
Backed by real source code from androidx/androidx and compose-multiplatform-core — not vibes.

Install

This skill is distributed as a plugin. See docs/INSTALL.md for per-host instructions:

Claude Code: /plugin marketplace add aldefy/compose-skill → /plugin install compose-expert
Copilot CLI: copilot plugin install aldefy/compose-skill
Codex CLI: manual install — see INSTALL.md.

Already installed manually? See docs/MIGRATION.md.

Updates

New versions are published as GitHub Releases with migration notes. Run /plugin update (Claude Code) or copilot plugin update aldefy/compose-skill (Copilot) to pick them up.

AI coding tools generate Compose code that compiles but gets the details wrong. Incorrect remember usage, unstable recompositions, broken modifier ordering, deprecated navigation patterns, hallucinated APIs that don't exist. They guess at behavior instead of knowing it.

This skill fixes that by giving your AI assistant two things:

24 reference guides covering every major Compose topic — including Compose Multiplatform, Android TV, Material 3 motion, atomic design systems, design-to-code workflows, animation recipes, Paging 3 (core / offline-first / MVI + testing), Nav 2 → Nav 3 migration, and production crash patterns
6 source code files pulled directly from androidx/androidx and compose-multiplatform-core so the agent can check how things actually work

What changes when you install it

Area	Without the skill	With it
State	Uses `remember { mutableStateOf() }` everywhere, even when `derivedStateOf` or `rememberSaveable` is the right call	Picks the right state primitive for each situation
Performance	Generates code that recomposes every frame	Applies stability annotations, deferred reads, `key {}` on lists
Navigation	String-based routes (deprecated)	Type-safe routes with `@Serializable` route classes
Modifiers	Random ordering, misses `clickable` before `padding` bugs	Correct ordering with reasoning
Side effects	Wrong coroutine scope, bad `LaunchedEffect` keys	Correct effect selection and lifecycle-aware keys
APIs	Hallucinates parameters that don't exist	Checks against actual source before suggesting
Multiplatform	Uses Android-only APIs in shared code	Uses `expect`/`actual`, `Res.*` resources, platform-correct patterns
Design-to-code	Literal Figma node translation, wrong modifier ordering	Semantic M3 components, correct ordering, theme tokens
Crash safety	No defensive patterns	Guards against zero-size DrawScope, duplicate keys, stale `derivedStateOf`

What's covered

Topic	What the agent learns
State management	`remember`, `mutableStateOf`, `derivedStateOf`, `rememberSaveable`, state hoisting, `snapshotFlow`
View composition	Structuring composables, slot APIs, `@Preview` patterns, extraction rules
Performance	Recomposition skipping, `@Stable`/`@Immutable`, deferred reads, baseline profiles, benchmarking
Navigation	Type-safe routes, `NavHost`, deep links, shared element transitions, back stack
Animation	`animate*AsState`, `AnimatedVisibility`, `Crossfade`, `updateTransition`, shared transitions, 9 recipes (shimmer, swipe-to-dismiss, etc.), gesture-driven patterns, Figma curve mapping
Lists and scrolling	`LazyColumn`/`LazyRow`/`LazyGrid`, `Pager`, `key {}`, `contentType`, scroll state
Side effects	`LaunchedEffect`, `DisposableEffect`, `SideEffect`, `rememberCoroutineScope`
Modifiers	Ordering rules, custom modifiers, `Modifier.Node` migration
Theming	`MaterialTheme`, `ColorScheme`, dynamic color, `Typography`, shapes, dark theme
Accessibility	Semantics, content descriptions, traversal order, touch targets, TalkBack
CompositionLocals	`LocalContext`, `LocalDensity`, custom locals, when to use vs. parameter passing
Deprecated patterns	Removed APIs, migration paths from older Compose versions
Styles API (experimental)	`Style {}`, `MutableStyleState`, `Modifier.styleable()`, composition, theme integration, alpha06 gotchas
Design-to-code	Composable decomposition algorithm, Figma property mapping, spacing ownership, modifier ordering, design tokens
Production crash playbook	6 crash patterns with root cause + fix, defensive patterns, production state/performance rules
Compose Multiplatform	CMP architecture, `expect`/`actual`, `Res.*` resources, API availability matrix, migration guide
Platform specifics	Desktop (Window, Tray, MenuBar), iOS (UIKitView, gotchas), Web/WASM (canvas limitations)
TV Compose	TV Material3 (Surface, Cards, Carousel, NavigationDrawer, TabRow), focus system, D-pad navigation, theming, immersive list, TVProvider
M3 Motion	All duration tokens (`DurationShort1–4`, `DurationMedium1–4`, `DurationLong1–4`, `DurationExtraLong1–4`), easing tokens with CubicBezierEasing values, `MotionScheme` API (`defaultSpatialSpec`, `defaultEffectsSpec`), Compose API mapping, decision tree, PR review flags
Atomic design	5-level hierarchy (tokens, atoms, molecules, organisms, templates) mapped to Compose, M3 wrapper patterns, custom atom patterns, slot API contracts, token layer, anti-patterns
Paging 3	`PagingSource`, `Pager`, `PagingConfig`, `LazyPagingItems`, `LoadState` UI handling, `flatMapLatest` for filter changes, `RemoteMediator` offline-first, MVI dual-flow pattern, `asSnapshot`/`TestPager`, full anti-pattern table
Nav 2 → Nav 3 migration	Conceptual shifts (you own the back stack), mechanical migration steps (`NavKey`, `rememberNavBackStack`, `NavDisplay`, entry-scoped ViewModels, deep-link parsing), original "Choosing Nav 2 vs Nav 3" decision guide with the CMP 1.10+ polymorphic-serialisation caveat
Source code	Actual `.kt` from `androidx/androidx` and `compose-multiplatform-core` for runtime, UI, foundation, material3, navigation, CMP

How it works

You ask about Compose
        |
        v
  AI reads SKILL.md (workflow + checklists)
        |
        v
  Consults the right reference file
        |
        +-- state-management.md
        +-- performance.md
        +-- navigation.md
        +-- design-to-compose.md
        +-- production-crash-playbook.md
        +-- multiplatform.md
        +-- platform-specifics.md
        +-- tv-compose.md
        +-- ... (20 guides total)
        |
        +-- source-code/
              +-- runtime-source.md
              +-- material3-source.md
              +-- cmp-source.md
              +-- ... (6 source files)

Layer 1: guidance docs (24 files) — practical references with patterns, pitfalls, and do/don't examples. The skill's ## Quick Routing section maps task signals to a single file so the agent lands on the right reference in one read.

Layer 2: source code receipts (6 files) — the actual Kotlin source from androidx/androidx and compose-multiplatform-core. When the agent needs to verify an implementation detail rather than guess, it reads these.

File structure

skills/compose-expert/
├── SKILL.md                              # Main workflow + checklists
└── references/
    ├── state-management.md               # State, remember, hoisting, derivedStateOf
    ├── view-composition.md               # Structuring composables, slots, previews
    ├── modifiers.md                      # Modifier ordering, custom modifiers, Modifier.Node
    ├── side-effects.md                   # LaunchedEffect, DisposableEffect, SideEffect
    ├── composition-locals.md             # CompositionLocal, LocalContext, custom locals
    ├── lists-scrolling.md                # LazyColumn/Row/Grid, Pager, keys, contentType
    ├── navigation.md                     # NavHost, type-safe routes, deep links (Nav 2)
    ├── navigation-migration.md           # Nav 2 → Nav 3 migration + decision guide
    ├── paging.md                         # Paging 3 core: PagingSource, Pager, LazyPagingItems
    ├── paging-offline.md                 # RemoteMediator, offline-first, LoadState gotchas
    ├── paging-mvi-testing.md             # MVI dual-flow pattern, asSnapshot, TestPager
    ├── animation.md                      # animate*AsState, AnimatedVisibility, transitions
    ├── theming-material3.md              # MaterialTheme, ColorScheme, dynamic color
    ├── performance.md                    # Recomposition, stability, benchmarking
    ├── accessibility.md                  # Semantics, content descriptions, testing
    ├── deprecated-patterns.md            # Removed APIs, migration paths
    ├── styles-experimental.md           # Styles API (@ExperimentalFoundationStyleApi)
    ├── design-to-compose.md             # Figma/screenshot decomposition, property mapping
    ├── production-crash-playbook.md     # Crash patterns, defensive coding, production rules
    ├── multiplatform.md                 # CMP architecture, expect/actual, Res.*, migration
    ├── platform-specifics.md            # Desktop, iOS, Web/WASM platform APIs and gotchas
    ├── tv-compose.md                    # Android TV: tv-material, Carousel, focus, D-pad
    ├── atomic-design.md                 # Atomic design system: tokens, atoms, molecules, organisms, templates
    └── source-code/                      # Actual .kt source
        ├── runtime-source.md             # Composer, Recomposer, State, Effects
        ├── ui-source.md                  # AndroidCompositionLocals, Modifier, Layout
        ├── foundation-source.md          # LazyList, BasicTextField, Gestures
        ├── material3-source.md           # MaterialTheme, all M3 components
        ├── navigation-source.md          # NavHost, ComposeNavigator
        └── cmp-source.md                # Window, UIKitView, ComposeViewport, Resources

Setup

The skill is just markdown files. Every tool below reads the same content. Pick yours.

Claude Code

Skills are file-based — Claude Code discovers them automatically from ~/.claude/skills/ (personal) or .claude/skills/ (project-specific).

Personal skill (available in all your projects):

Clone the repo and copy the skill into your personal skills directory:

git clone https://github.com/aldefy/compose-skill.git /tmp/compose-skill
mkdir -p ~/.claude/skills
cp -r /tmp/compose-skill/skills/compose-expert ~/.claude/skills/

Project-specific skill (just one project):

Clone the repo and copy the skill into your project's .claude/skills directory:

git clone https://github.com/aldefy/compose-skill.git /tmp/compose-skill
mkdir -p .claude/skills
cp -r /tmp/compose-skill/skills/compose-expert .claude/skills/

No CLI command or config file needed. Claude Code picks up SKILL.md from these directories automatically and triggers when you mention Compose, @Composable, remember, LazyColumn, NavHost, etc.

Codex CLI (OpenAI)

Add an AGENTS.md file to your project root:

# AGENTS.md

## Jetpack Compose
For all Compose/Android UI tasks, follow the instructions in
`skills/compose-expert/SKILL.md` and consult the reference
files in `skills/compose-expert/references/` before answering.

Add the skill to your project as a submodule:

git submodule add https://github.com/aldefy/compose-skill.git .compose-skill

Codex discovers AGENTS.md files automatically from the git root down to the current directory.

Gemini CLI (Google)

Add to GEMINI.md in your project root:

# GEMINI.md

## Jetpack Compose Expert
For all Jetpack Compose tasks, follow the workflow and checklists in
`skills/compose-expert/SKILL.md`.

Before answering any Compose question, consult the relevant reference:
- State management -> `skills/compose-expert/references/state-management.md`
- Performance -> `skills/compose-expert/references/performance.md`
- Navigation -> `skills/compose-expert/references/navigation.md`
- (see SKILL.md for the full topic -> file mapping)

For implementation details, check actual source code in
`skills/compose-expert/references/source-code/`.

Add as a submodule:

git submodule add git@github.com:aldefy/compose-skill.git .compose-skill

Google Antigravity

Antigravity automatically discovers skills from workspace or global skill folders. The skills/compose-expert directory acts as a complete, ready-to-use Antigravity skill since it contains the needed SKILL.md file with a YAML frontmatter description.

Workspace skill (project-specific):

# Clone the repo
git clone https://github.com/aldefy/compose-skill.git /tmp/compose-skill

# Copy into your project's .agents/skills directory
mkdir -p .agents/skills
cp -r /tmp/compose-skill/skills/compose-expert .agents/skills/compose-expert

Global skill (available in all your projects):

# Clone the repo
git clone https://github.com/aldefy/compose-skill.git /tmp/compose-skill

# Copy into your global Antigravity skills directory
mkdir -p ~/.gemini/antigravity/skills
cp -r /tmp/compose-skill/skills/compose-expert ~/.gemini/antigravity/skills/compose-expert

Cursor

Create .cursor/rules/compose-skill.mdc:

---
description: Jetpack Compose expert guidance
globs: **/*.kt
---

Follow the instructions in `skills/compose-expert/SKILL.md`
for all Compose-related code. Consult reference files in
`skills/compose-expert/references/` before suggesting patterns.

Or paste the contents of SKILL.md into Settings > Rules for AI.

GitHub Copilot

Add to .github/copilot-instructions.md:

## Jetpack Compose
For Compose/Android UI work, follow the skill instructions in
`skills/compose-expert/SKILL.md`. Consult reference files in
`skills/compose-expert/references/` for patterns, pitfalls,
and source-code-backed guidance.

Windsurf

Create .windsurf/rules/compose-skill.md in your project root:

For all Jetpack Compose tasks, follow the workflow in
`skills/compose-expert/SKILL.md` and consult the reference
files in `skills/compose-expert/references/` before answering.

Note: The legacy .windsurfrules file also works but .windsurf/rules/ is the current approach.

Amazon Q Developer

Add to .amazonq/rules/compose.md:

For all Jetpack Compose tasks, follow the workflow in
`skills/compose-expert/SKILL.md` and consult the reference
files in `skills/compose-expert/references/` before answering.

Any other AI coding tool

It's just markdown. Clone this repo into your project (or add as a submodule), then point your tool's instruction file at skills/compose-expert/SKILL.md. The agent reads SKILL.md for the workflow and pulls from references/ as needed.

Quick example

After setup, just talk to your AI assistant normally:

"My LazyColumn is janky when scrolling — help me fix it"

What happens:

Agent reads SKILL.md for the workflow
Pulls in references/lists-scrolling.md and references/performance.md
Checks your code for missing key {}, unstable item types, heavy compositions in item blocks
If something's unclear, verifies against references/source-code/foundation-source.md
Gives you a fix based on the actual LazyList implementation

No hallucinated APIs. No guessed behavior.

Source

Source code comes from androidx/androidx and JetBrains/compose-multiplatform-core under Apache License 2.0. The guidance docs are original analysis of those sources plus official documentation.

Contributing

PRs welcome, especially:

Additional platform-specific gotchas and workarounds
New animation recipes for common UI patterns
Production crash patterns from real apps
Corrections based on newer Compose/CMP releases
Auto-update tooling for tracking new releases

License

MIT — see LICENSE.

Source code from androidx/androidx is Apache License 2.0, copyright The Android Open Source Project. Source code from compose-multiplatform-core is Apache License 2.0, copyright JetBrains s.r.o.