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.

The problem

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:

1. 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
2. 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

What's covered

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:

1. Agent reads SKILL.md for the workflow
2. Pulls in references/lists-scrolling.md and references/performance.md
3. Checks your code for missing key {}, unstable item types, heavy compositions in item blocks
4. If something's unclear, verifies against references/source-code/foundation-source.md
5. 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.