compose-skill

KO | EN

gitlite — search

#react #python #javascript #hacktoberfest #webpack #docker #electron #android #plugin #macos #metrics #aws

★ 277 Open GitHub ↗

AI agent skill for Jetpack Compose & Compose Multiplatform (KMP/CMP). MVI architecture, Navigation 3, Koin/Hilt, Ktor, Room, DataStore, Paging 3, Coil, coroutines/Flow, animations, performance, accessibility, testing, and cross-platform patterns. Works with Codex, Cursor, Claude Code.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">compose-skill</h1>

Make your AI coding tool actually understand Compose. 
 A comprehensive agent skill for Jetpack Compose and Compose Multiplatform (KMP/CMP).

---

## What This Skill Does

This is an **AI agent skill** — not a library, not documentation. Install it once, and your AI coding agent (Codex, Cursor, Claude Code) gains production-grade knowledge of the entire Compose app development lifecycle: architecture, UI, state, navigation, networking, persistence, performance, accessibility, cross-platform, build configuration, distribution, and code review.

The skill covers **Android**, **iOS**, **Desktop**, and **Web** targets with the same architectural principles.

## What's Covered

<table>
 <tr>
 <td align="center" width="33%">🏗️ Architecture & State</td>
 <td align="center" width="33%">🎨 Compose UI</td>
 <td align="center" width="33%">🌐 Data & Networking</td>
 </tr>
 <tr>
 <td valign="top">
 MVI with Event, State, Effect 
 Unidirectional data flow 
 ViewModel patterns 
 State modeling (4 buckets) 
 Clean code & anti-patterns
 </td>
 <td valign="top">
 Three-phase model & side effects 
 Coil 3 image loading 
 Lists, grids, pagers & keying 
 Shared element animations 
 Material 3 theming & adaptive
 </td>
 <td valign="top">
 Ktor HTTP client & auth flows 
 DTO-to-domain mapping 
 Room Database (KMP) 
 DataStore (Preferences & Typed) 
 Paging 3 with MVI
 </td>
 </tr>
 <tr><td colspan="3"></td></tr>
 <tr>
 <td align="center">🧭 Navigation & DI</td>
 <td align="center">⚡ Performance & Quality</td>
 <td align="center">📱 Cross-Platform</td>
 </tr>
 <tr>
 <td valign="top">
 Navigation 3 &amp; Nav 2 
 Tabs, scenes, deep links 
 Koin (CMP) & Hilt (Android) 
 ViewModel scoping
 </td>
 <td valign="top">
 Recomposition minimization 
 Compiler Metrics & profiles 
 Turbine testing 
 Macrobenchmark & UI tests 
 Accessibility & WCAG
 </td>
 <td valign="top">
 KMP <code>commonMain</code> sharing 
 <code>expect/actual</code> patterns 
 iOS interop (SKIE) 
 CMP resources & localization 
 Gradle/AGP 9+, CI/CD, signing
 </td>
 </tr>
</table>

## Without vs With compose-skill

| Concern | Without | With |
|:--------|:--------|:-----|
| **State management** | Scattered `mutableStateOf` in composables | Single `StateFlow<State>` owned by ViewModel |
| **Business logic** | Mixed into UI layer | Isolated in ViewModel's `onEvent()` handler |
| **One-shot actions** | Boolean flags in state | `Channel<Effect>` for navigation, snackbar |
| **Recomposition** | Frequent, hard to diagnose | Minimized via state shape and read boundaries |
| **Navigation** | Ad-hoc calls from composables | Semantic effects, route layer executes |
| **Networking** | Inconsistent error handling | Ktor + `Result`/`ApiResult` wrapper, DTO mappers |
| **Persistence** | Raw SharedPreferences | DataStore + Room with MVI integration |
| **Accessibility** | Missing or incorrect semantics | `contentDescription`, touch targets, WCAG contrast |
| **Cross-platform** | Android-only or inconsistent | `commonMain` with `expect/actual` for platform APIs |
| **Build config** | Hardcoded versions | Version catalog, AGP 9+ patterns, conventions |
| **Testing** | Manual UI testing | ViewModel event→state→effect via Turbine |
| **Code review** | Inconsistent patterns | Anti-pattern detection with documented fixes |

## Installation

Pick your agent and run **one command**. The clone target becomes the skill folder — agents detect `SKILL.md` at the root automatically.

> **Only three things matter for the skill to work:** `SKILL.md`, `agents/`, and `references/`. Everything else in this repo (README, LICENSE, scripts, assets, .github) is for documentation, validation, and CI — the agent never reads them. If you prefer a minimal install, you only need those three.

> **Why is `SKILL.md` at the root?** All three agents (Codex, Cursor, Claude Code) look for `SKILL.md` at the **top level** of the skill directory. This repo is structured so that cloning it directly into the skill path gives you a ready-to-use skill — no moving files or extra nesting required.

> Skill installation paths may change as agents evolve. The locations below are accurate at the time of writing — for the latest instructions, refer to each agent's official docs or ask your agent *"How do I add a skill?"*
> - [Codex Skills docs](https://developers.openai.com/codex/skills/) · [Cursor Skills docs](https://www.cursor.com/docs/context/skills) · [Claude Code Skills docs](https://code.claude.com/docs/en/slash-commands)

### Quick Install (copy-paste)

| Client | User-global | Per-repo |
|:-------|:------------|:---------|
| **Codex** | `~/.codex/skills/compose-skill` | `.codex/skills/compose-skill` |
| **Cursor** | `~/.cursor/skills/compose-skill` | `.cursor/skills/compose-skill` |
| **Claude Code** | `~/.claude/skills/compose-skill` | `.claude/skills/compose-skill` |
| **Other agents** | Upload `SKILL.md`, `agents/`, and `references/` as project knowledge | — |

```bash
# Replace <path> with the install location from the table above
git clone https://github.com/Meet-Miyani/compose-skill.git <path>

# Examples:
git clone https://github.com/Meet-Miyani/compose-skill.git ~/.cursor/skills/compose-skill
git clone https://github.com/Meet-Miyani/compose-skill.git .codex/skills/compose-skill
```

## Common Mistakes

| Problem | Fix |
|:--------|:----|
| Folder named `compose-skill-main` | Rename to `compose-skill` (GitHub ZIP downloads add `-main`) |
| `SKILL.md` not at root of skill folder | Don't nest inside another directory — clone directly into the skill path |
| Skill not detected after install | Restart the agent / IDE |

## Verify Activation

| Client | How to verify |
|:-------|:--------------|
| **Codex** | Run `/skills` — `compose-skill` appears in the list |
| **Cursor** | **Settings → Rules** — skill appears under *Agent Decides* |
| **Claude Code** | Run `/skills` or ask *"What skills are available?"* |

## Usage

Once installed, the skill activates **automatically** when your prompt matches its triggers (`@Composable`, `StateFlow`, `ViewModel`, `KMP`, `Ktor`, `recomposition`, `DataStore`, etc.). You can also invoke it **explicitly** — the syntax varies by client:

| Client | Explicit invocation | Automatic |
|:-------|:-------------------|:----------|
| **Codex CLI** | `$compose-skill` in your prompt | Yes |
| **Codex IDE extension** | `$compose-skill` in chat | Yes |
| **Codex App** | `/compose-skill` in chat | Yes |
| **Cursor** | `/compose-skill` in Agent chat | Yes |
| **Claude Code** | `/compose-skill` in chat | Yes |

### Invocation Examples

**Codex CLI / IDE extension** — dollar-sign prefix:
```text
$compose-skill Refactor this screen to MVI with proper state modeling.
```

**Codex App / Cursor / Claude Code** — slash prefix:
```text
/compose-skill How do I set up Paging 3 with MVI in a KMP project?
```

## Skill Structure

```text
compose-skill/
│
│   ## Required (the skill itself) ─────────────────────
├── SKILL.md                            # Skill definition — agent reads this
├── agents/
│   └── openai.yaml                     # Codex UI metadata
└── references/                         # 37 deep-dive reference files
    │                                   #   (loaded on-demand by SKILL.md)
    ├── architecture.md
    ├── coroutines-flow.md
    ├── compose-essentials.md
    ├── material-design.md
    ├── image-loading.md
    ├── lists-grids.md
    ├── paging.md
    ├── paging-offline.md
    ├── paging-mvi-testing.md
    ├── navigation.md
    ├── navigation-3.md
    ├── navigation-2.md
    ├── navigation-3-di.md
    ├── navigation-2-di.md
    ├── navigation-migration.md
    ├── performance.md
    ├── animations.md
    ├── ui-ux.md
    ├── testing.md
    ├── room-database.md
    ├── datastore.md
    ├── networking-ktor.md
    ├── networking-ktor-auth.md
    ├── networking-ktor-testing.md
    ├── networking-ktor-architecture.md
    ├── dependency-injection.md
    ├── koin.md
    ├── hilt.md
    ├── cross-platform.md
    ├── resources.md
    ├── ios-swift-interop.md
    ├── accessibility.md
    ├── clean-code.md
    ├── anti-patterns.md
    ├── gradle-build.md
    └── ci-cd-distribution.md
│
│   ## Optional (repo extras) ──────────────────────────
├── README.md                           # This file (not read by agents)
├── LICENSE                             # MIT License
├── assets/
│   └── compose-multiplatform-icon.svg  # Logo for README
└── scripts/
    └── validate.sh                     # Skill scanner / validation tool
```

## Reference Guide

The `references/` directory contains 37 deep-dive files that the skill loads on-demand. Here's what each one covers in detail:

<details>
<summary>Kotlin Foundations</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **coroutines-flow.md** | StateFlow vs SharedFlow vs Channel decision table, Flow operators (`flatMapLatest`, `combine`, `debounce`, `catch`), Dispatchers (IO/Default/Main), structured concurrency (`viewModelScope`, `supervisorScope`), exception handling, `CancellationException`, `stateIn`/`shareIn`, backpressure (`buffer`/`conflate`/`collectLatest`), `callbackFlow`, Mutex/Semaphore, testing with Turbine |

</details>

<details>
<summary>Architecture</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **architecture.md** | ViewModel/event-handling pipeline, state modeling, Channel vs SharedFlow for effects, domain layer rules, inter-feature communication (event bus, feature API contracts), module dependency rules, GOOD/BAD code examples |
| **clean-code.md** | Avoiding overengineering, file organization, naming conventions, disciplined vs bloated MVI comparison |
| **anti-patterns.md** | Cross-cutting anti-pattern quick-reference table with "why it hurts" and "better replacement" for each, plus routing index to domain-specific anti-patterns in other reference files |

</details>

<details>
<summary>Compose APIs</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **material-design.md** | M3 theme setup (dynamic color, dark/light, color roles), typography/shapes, component decisions (Scaffold, TopAppBar, NavigationBar/Rail/Suite, BottomSheet, Snackbar, Dialog), adaptive layouts (window size classes, canonical layouts), M2→M3 migration |
| **image-loading.md** | Coil 3 setup for Compose/CMP, `AsyncImage`/`rememberAsyncImagePainter`/`SubcomposeAsyncImage` decision guide, placeholder/error/fallback/crossfade, memory/disk/network cache policy, transformations vs `Modifier.clip`, SVG (`coil-svg`), `Res.getUri` resource loading |
| **compose-essentials.md** | Three phases model, state primitives, side effects (`LaunchedEffect`, `DisposableEffect`, `rememberUpdatedState`), modifier ordering, `graphicsLayer`, slot pattern, `CompositionLocal`, `collectAsStateWithLifecycle` |
| **lists-grids.md** | LazyColumn/LazyRow, keys, `contentType`, grids, pager, scroll state, nested scrolling, list anti-patterns |
| **paging.md** | PagingSource, Pager + ViewModel setup (PagingData as separate Flow, never in UiState), `cachedIn`, filter/search with `flatMapLatest`, `LazyPagingItems` (all lazy layouts), LoadState handling, PagingData transformations, `PagingSource.invalidate()` |
| **paging-offline.md** | RemoteMediator offline-first with Room, `initialize()` (`LAUNCH_INITIAL_REFRESH` vs `SKIP_INITIAL_REFRESH`), remote keys, Pager wiring |
| **paging-mvi-testing.md** | MVI dual-flow pattern (PagingData separate from UiState), route collection, PagingSource unit tests, `asSnapshot`, `TestPager`, anti-patterns table |
| **navigation.md** | Shared navigation concepts: Nav 2 vs Nav 3 decision guide, MVI navigation rules (both versions), anti-patterns table, routing to version-specific files |
| **navigation-3.md** | Nav 3 full reference: route definition, back stack persistence, `NavDisplay` full API, top-level tabs (`NavigationSuiteScaffold`), ViewModel scoping with entry decorators, Scenes (dialog, bottom sheet, list-detail, Material Adaptive), animations, back stack manipulation, deep links, CMP polymorphic serialization |
| **navigation-2.md** | Nav 2 full reference: `NavHost`/`NavController`, type-safe routes (2.8+), string routes, top-level tabs (`NavigationBar` + `currentBackStackEntryAsState` + `saveState`/`restoreState`), deep links (`NavDeepLink`), navigate with results (`SavedStateHandle`), nested graphs, animations (`enterTransition`/`exitTransition`), conditional navigation (auth guards), predictive back |
| **navigation-3-di.md** | Nav 3 + DI wiring: Hilt `hiltViewModel` in entry blocks + `@AssistedInject` + multibinding entry providers, Koin `navigation<T>` DSL + `koinEntryProvider()`, modularization api/impl split, entry-scoped VMs via decorators |
| **navigation-2-di.md** | Nav 2 + DI wiring: Hilt `hiltViewModel` in composable destinations + graph-scoped VMs via `getBackStackEntry` + `SavedStateHandle`, Koin `koinViewModel` + `koinNavViewModel` + `sharedKoinViewModel` for graph-scoped sharing |
| **navigation-migration.md** | Nav 2 to Nav 3 migration: conceptual shift table, step-by-step migration (routes → NavKey, controller → backStack, NavHost → NavDisplay, graph VMs → entry decorators, deep links, tabs), incremental strategy, coexistence |

</details>

<details>
<summary>Performance & Quality</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **performance.md** | Three phases, primitive state specializations, `TextFieldState`, Strong Skipping Mode, stability config, Compose Compiler Metrics, baseline profiles, API decision table, 20 recomposition rules, diagnostic checklist |
| **animations.md** | Complete animation API reference: decision tree, `AnimationSpec` (spring/tween/keyframes), `animate*AsState`, `Animatable` (sequential, concurrent, gesture-driven), `updateTransition`, `AnimatedVisibility`, `AnimatedContent`, shared element transitions with navigation and Coil, swipe-to-dismiss, Canvas/custom drawing, `graphicsLayer`, performance optimization |
| **ui-ux.md** | Loading states, skeleton/shimmer, preserving content during refresh, inline validation, perceived performance |
| **accessibility.md** | `contentDescription` rules, `Modifier.semantics` (role, stateDescription, heading), `mergeDescendants`, `clearAndSetSemantics`, touch targets (48dp), WCAG color contrast, custom interactive elements, custom accessibility actions |
| **testing.md** | Turbine for StateFlow testing, ViewModel event→state→effect testing, validation/UI tests, Macrobenchmark, lean test matrix by app scale |

</details>

<details>
<summary>Data & Persistence</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **datastore.md** | KMP + Android setup, Preferences DataStore keys/read/write, Typed DataStore with JSON serialization, singleton enforcement, corruption handling, SharedPreferences migration, MVI integration, DI wiring, testing, anti-patterns |
| **room-database.md** | Entity design, performance-oriented DAOs, indexes, relationships (`@Embedded`/`@Relation`/`@Junction`), TypeConverters, transactions, migrations, MVI integration, anti-patterns |

</details>

<details>
<summary>Networking, DI & Cross-Platform</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **networking-ktor.md** | HttpClient configuration, platform engines, plugins (ContentNegotiation, Retry, Timeout, Logging, ContentEncoding), custom plugins (`createClientPlugin`), DTOs, mappers, API service (CRUD, multipart), repository pattern, proxy/SSL |
| **networking-ktor-auth.md** | Bearer token auth with refresh, WebSockets (frames, serialization converter, session), SSE (Server-Sent Events) |
| **networking-ktor-testing.md** | MockEngine setup (success, error, request assertions, multiple responses), engine injection, Koin/Hilt DI integration, testing anti-patterns |
| **networking-ktor-architecture.md** | `Result` vs `ApiResult` decision, `safeRequest` wrapper, exception classification, plugin composition strategy, client factory design, response observation plugin, debug vs production, architecture anti-patterns |
| **dependency-injection.md** | DI decision guide (Hilt vs Koin), shared concepts |
| **koin.md** | Koin setup for CMP and Android, module organization, `koinViewModel`, `koinInject`, Koin + Nav 3 (`navigation<T>`, `koinEntryProvider`), scoped navigation, MVI ViewModel integration, testing |
| **hilt.md** | Android-only Hilt setup, `@HiltViewModel`, `hiltViewModel()`, modules (`@Provides`/`@Binds`), scopes, Navigation Compose integration, MVI pattern with Hilt, testing |
| **cross-platform.md** | `commonMain` vs platform placement, interfaces vs `expect/actual`, platform bridge patterns (interface+DI, expect/actual, typealias), lifecycle, state restoration, resources, accessibility |
| **ios-swift-interop.md** | Kotlin→Swift naming, nullability/collection bridging, SKIE setup, suspend→async, Flow→AsyncSequence, sealed class mapping, SwiftUI/UIKit interop (`ComposeUIViewController`, `UIKitView`), iOS API design rules |
| **resources.md** | Android `R` vs CMP `Res` comparison, `composeResources/` directory structure, Gradle setup, drawable/string/plural/font/raw-file APIs with code examples, qualifiers (language, theme, density), localization, generated resource maps, Android assets interop (`Res.getUri`), MVI integration |

</details>

<details>
<summary>Build, Distribution & CI/CD</summary>

| Reference | What's Inside |
|:----------|:-------------|
| **gradle-build.md** | AGP 9+ project structure, version catalog (`[versions]`/`[libraries]`/`[plugins]`/`[bundles]`), bundle patterns, composite builds (`includeBuild` + `dependencySubstitution`), private Maven repos, `settings.gradle.kts`, `gradle.properties`, module-level build scripts, `compileSdk { version = release(N) }`, KSP/Room/Koin wiring, convention plugins guidance |
| **ci-cd-distribution.md** | GitHub Actions workflows (Android APK, Desktop multi-OS DMG/MSI/DEB), desktop app module setup (`compose.desktop`), iOS Xcode framework integration, signing/notarization (Android/macOS/iOS), adding JVM desktop target to existing CMP project, Gradle task reference table |

</details>

## Example Prompts

<details>
<summary>Architecture & State</summary>

```text
Refactor this Compose screen to MVI.
How should I structure a KMP feature module with Compose UI and ViewModel?
Audit this feature against the compose-skill and list anti-patterns first, then apply minimal fixes.
```
</details>

<details>
<summary>UI & Performance</summary>

```text
I have too much recomposition in this form screen. What should I change?
Optimize recomposition in this screen and explain each state-shape change.
Add shared element transitions between my list and detail screens.
```
</details>

<details>
<summary>Data & Networking</summary>

```text
Set up Ktor with bearer token auth and refresh for my KMP project.
Should this be SharedFlow or Channel for one-off effects?
How do I use DataStore for user preferences in a KMP app?
```
</details>

<details>
<summary>Cross-Platform & Distribution</summary>

```text
How do I expose this Kotlin StateFlow to Swift using SKIE?
Set up GitHub Actions to build DMG, MSI, and DEB for my desktop app.
Add iOS target to my existing Compose Multiplatform project.
```
</details>

<details>
<summary>Accessibility & Quality</summary>

```text
Review this screen for accessibility issues.
How do I make my custom interactive component accessible?
Set up ViewModel tests with Turbine for this feature.
```
</details>

## Official Documentation

| Resource | Link |
|:---------|:-----|
| Jetpack Compose | [developer.android.com/compose](https://developer.android.com/develop/ui/compose) |
| Compose Multiplatform | [jetbrains.com/compose-multiplatform](https://www.jetbrains.com/compose-multiplatform/) |
| Kotlin Coroutines | [kotlinlang.org/coroutines](https://kotlinlang.org/docs/coroutines-overview.html) |
| StateFlow & SharedFlow | [kotlinlang.org/flow](https://kotlinlang.org/docs/flow.html#stateflow-and-sharedflow) |
| ViewModel | [developer.android.com/viewmodel](https://developer.android.com/topic/libraries/architecture/viewmodel) |
| Navigation 3 | [developer.android.com/navigation](https://developer.android.com/develop/ui/compose/navigation) |
| Coil | [coil-kt.github.io/coil](https://coil-kt.github.io/coil/) |
| Paging 3 | [developer.android.com/paging](https://developer.android.com/topic/libraries/architecture/paging/v3-overview) |
| Room | [developer.android.com/room](https://developer.android.com/training/data-storage/room) |
| DataStore | [developer.android.com/datastore](https://developer.android.com/topic/libraries/architecture/datastore) |
| Ktor Client | [ktor.io/docs/client](https://ktor.io/docs/client.html) |
| Koin | [insert-koin.io](https://insert-koin.io/docs/reference/koin-compose/compose/) |
| Hilt | [developer.android.com/hilt](https://developer.android.com/training/dependency-injection/hilt-android) |
| Agent Skills Standard | [agentskills.io](https://agentskills.io/) |

## Contributing

Contributions are welcome! Whether it's fixing a typo, improving a reference doc, or adding coverage for a new Compose API — all help is appreciated.

1. **Fork** the repository
2. **Create a branch** for your change (`git checkout -b improve-navigation-docs`)
3. **Make your changes** — keep reference files focused and under 500 lines where possible
4. **Run the scanner** to verify everything passes:
   ```bash
   ./scripts/validate.sh
   ```
5. **Open a pull request** with a clear description of what changed and why

### Guidelines

- Follow the [agentskills.io specification](https://agentskills.io/specification) for any structural changes
- Keep `SKILL.md` body under 500 lines — move detailed content to `references/`
- Every reference file in `references/` should be linked from `SKILL.md`
- Use code examples that compile and follow the skill's MVI conventions
- Don't add dependencies — the skill is pure markdown and bash

## License

This project is licensed under the [MIT License](LICENSE).

---

Built for <a href="https://developer.android.com/develop/ui/compose">Jetpack Compose</a> and <a href="https://www.jetbrains.com/compose-multiplatform/">Compose Multiplatform</a>. 
 Works with <a href="https://developers.openai.com/codex">Codex</a>, <a href="https://www.cursor.com">Cursor</a>, <a href="https://code.claude.com">Claude Code</a>, and any <a href="https://agentskills.io/">Agent Skills</a>-compatible tool.

compose-skill

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README