compose-skill

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

Without vs With compose-skill

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 · Cursor Skills docs · Claude Code Skills docs

Quick Install (copy-paste)

# 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

Verify Activation

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:

Invocation Examples

Codex CLI / IDE extension — dollar-sign prefix:

$compose-skill Refactor this screen to MVI with proper state modeling.

Codex App / Cursor / Claude Code — slash prefix:

/compose-skill How do I set up Paging 3 with MVI in a KMP project?

Skill Structure

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:

Example Prompts

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.

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.

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?

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.

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

Official Documentation

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:

   ./scripts/validate.sh
   

5. Open a pull request with a clear description of what changed and why

Guidelines

• Follow the 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.

Built for Jetpack Compose and Compose Multiplatform.
Works with Codex, Cursor, Claude Code, and any Agent Skills-compatible tool.