# A Compose skill that ships the framework's own source as a reference > An agent skill covering twenty-four Compose topics, backed by six source files taken directly from the AndroidX and Compose Multiplatform repositories so the assistant can check behaviour rather than guess it. The failure mode it targets is code that compiles and still does the wrong thing. **aldefy/compose-skill** — Jetpack Compose Agent Skill — AI-powered coding guidance with actual androidx/androidx source code receipts. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Copilot, Windsurf, and more. - Repository: https://github.com/aldefy/compose-skill - Stars: 594 · Forks: 38 - Language: Kotlin - License: NOASSERTION - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/aldefy-compose-skill ## The target failure is code that compiles and misbehaves The problem statement is specific enough to be testable, which is unusual for this category of tool. The claim is that AI coding tools generate Compose code which builds successfully and still gets the details wrong. The named errors are: incorrect use of the state primitive, unstable recompositions, broken modifier ordering, deprecated navigation patterns, and invented APIs that do not exist. The last one is the most severe and the one the skill's structure is built around. A hallucinated parameter produces a compile error the developer catches immediately. A misapplied state primitive produces an app that builds, runs, and recomposes far more than it should. The diagnosis given is that the model guesses at behaviour rather than knowing it. Guessing is not a knowledge problem, so more documentation does not fix it; the fix is to let the assistant check. That framing explains the rest of the design. Everything here is either a way of making behaviour checkable or a written-down list of the specific mistakes worth avoiding. The target platforms are stated up front: Android, desktop, iOS and web, with the last two running through the Compose Multiplatform layer rather than the Android-specific one. ## Twenty-four guides and six real source files The skill supplies exactly two kinds of material. The first is twenty-four reference guides covering the major topics, and the list is long enough to show what the author considers a complete working surface: state management, composition, performance, navigation, animation, lists and scrolling, side effects, modifiers, theming, accessibility, composition locals, deprecated patterns, a multiplatform guide, platform specifics for each target, and an experimental styles guide. The second is six source code files, taken directly from the AndroidX repository and from the Compose Multiplatform core repository, covering the runtime, UI, foundation, material, navigation and multiplatform modules. That second category is the differentiator. The stated purpose is so the agent can check how things actually work, and the framing in the readme is that the guidance is backed by real source code receipts rather than assertion. Shipping source is a heavier commitment than shipping prose. It means the skill has to track framework versions, because source from the wrong release teaches the wrong thing, and it means the repository grows a build step to extract those files rather than copying them by hand. The workflow the assistant is instructed to follow is a short pipeline: read the main skill definition for workflow and checklists, then consult whichever reference file matches the question. ## The before-and-after table is the real specification There is a table comparing behaviour with and without the skill, and it is the most useful page in the repository. Each row names an area, the wrong pattern, and the right one. On state, the failure is reaching for the same memory primitive everywhere even when a derived-state primitive or the state-preserving variant is correct, and the fix is choosing per situation. On performance, the failure is code that recomposes every frame, and the fix is stability annotations, deferred reads and keying list items. On navigation, string-based routes are the deprecated failure and type-safe route classes are the fix. On modifiers, random ordering misses a class of click-versus-padding bug. On side effects, wrong coroutine scope and badly keyed effects. On crash safety, the specific failures named are a zero-size drawing scope, duplicate keys, and a stale derived-state read. Read together, the table is a specification of the skill's value rather than a feature list, and every row is a bug that would not surface as a compile error. The crash-safety row is the most specific, which suggests it came from production rather than from documentation review. Two rows are worth separating out because they are about correctness against an external system rather than against the framework. Hallucinated parameters are addressed by checking the actual source first. And translating a design file literally into components, with the wrong modifier order, is replaced with semantic components and theme tokens. ## Two hosts install as plugins, one does not Installation differs per host, and the difference is not cosmetic. The skill is distributed as a plugin, with per-host instructions in a separate document. For one host you add a marketplace and then install a plugin by name from it. For a second, a single install command with the repository named. For the third, the documentation says manual install and points at the instructions. ``` /plugin marketplace add aldefy/compose-skill /plugin install compose-expert copilot plugin install aldefy/compose-skill ``` So the plugin name installed is not the repository name, which is a small trap for anyone scripting the install. There is also a separate migration document, and it is addressed at people who already installed the skill manually rather than as a plugin. That implies the distribution changed at some point and left the two installation methods coexisting. Updates go through the plugin mechanism, and new versions are published as releases with migration notes attached. The description also names several other assistants as supported, including two beyond the three with documented install paths, so the plugin manifests cover more hosts than the install document walks through. ## A verification directory suggests the guidance is checked One entry in the repository layout deserves attention, and it is not obvious what it is for. Alongside the source, the documentation, the skills directory and a set of build files there is a directory whose name implies checking the claims in the skill itself. For a skill whose entire argument is that its assistant should verify behaviour against real source rather than assert it, having a mechanism that verifies the skill's own statements is the consistent thing to build. The build machinery is a Gradle project in the Kotlin language the skill teaches, with a wrapper and a separate build logic directory. So the skill is packaged by a build rather than assembled by hand, which is what makes it practical to refresh the extracted source files on each release. The presence of host-specific plugin manifest directories for two of the three hosts confirms that the repository is a package rather than a document, and that it knows which hosts it is shipping to. There is also a changelog and a contribution document, which for a package that ships versioned guidance are not optional. On maintenance, the last push to the default branch is dated 2026-07-23, the newest release is from early July, and the repository is not archived. ## Depth is concentrated in migration and multiplatform Looking at how the twenty-four guides are weighted reveals what the author found worth documenting. The baseline topics are covered thoroughly but conventionally: state, composition, performance, modifiers, theming, accessibility. Accessibility includes touch targets and traversal order rather than just semantics, which is the level that actually matters in review. Then the coverage becomes specific. The motion guide enumerates every duration token by name across four scales, the easing tokens with their curve values, and a motion scheme API with its two spec accessors, plus a decision tree and a list of things to flag in code review. That is not a tutorial, it is a lookup table. The migration guide is the deepest. Rather than only listing steps, it names the conceptual shift, gives the mechanical steps by symbol, and includes an original decision guide for choosing between the two navigation systems, with a caveat about polymorphic serialisation at a specific multiplatform version. Atomic design gets a five-level hierarchy mapped onto Compose concepts with a token layer and an anti-pattern list. Paging gets the offline-first and unidirectional-data-flow patterns with a full anti-pattern table. The crash playbook lists six patterns each with root cause and fix. So the distribution is telling: the common topics get solid treatment, and the places where developers actually get stuck, which are migrations and cross-platform builds, get the most space. ## Conclusion This suits anyone whose assistant writes Compose that compiles but subtly misbehaves, since the failure it targets is not syntax but semantics, and shipping actual framework source is the right corrective for that. It suits you less if you write in a language the twenty-four guides do not cover, where the skill is inert. Before installing, check which host you use, because one of the three documented paths is a manual install rather than a plugin command, and read the migration notes when you update, because the guidance itself is versioned and a stale copy is worse than none. ## FAQ ### What is the compose-skill used for? It teaches an AI coding assistant Jetpack Compose across Android, desktop, iOS and web, so the code it writes behaves correctly rather than merely compiling. The target is semantic errors such as wrong state primitives, unstable recompositions, bad modifier ordering and invented APIs. ### What does aldefy/compose-skill contain? Twenty-four reference guides covering the major Compose topics, plus six source files pulled directly from the AndroidX and Compose Multiplatform repositories so the assistant can check how the framework actually behaves instead of guessing. ### How do I install the Compose agent skill? It is distributed as a plugin. One host installs from a marketplace you add first, a second uses a single plugin install command, and a third requires manual installation. A separate migration document covers people who already installed it manually. ### What does installing the skill actually change? The repository tabulates it: the right state primitive is chosen per situation instead of one everywhere, stability annotations and keying are applied so code stops recomposing every frame, navigation moves to type-safe routes, modifier ordering becomes correct, and hallucinated parameters are checked against real source. ### How are compose-skill updates handled? New versions are published as releases with migration notes attached, and updates go through the plugin mechanism of the host. Because the guidance itself is versioned, the migration notes matter rather than being boilerplate. ### Which Compose topics get the most detail in compose-skill? The migrations and cross-platform work. The navigation migration guide includes the conceptual shift, mechanical steps by symbol, and a decision guide for choosing between the two navigation systems, while the motion guide enumerates every duration and easing token by name. ## Sources - [aldefy/compose-skill on GitHub](https://github.com/aldefy/compose-skill) - [Issues](https://github.com/aldefy/compose-skill/issues) - [README](https://github.com/aldefy/compose-skill/blob/master/README.md) - [Releases](https://github.com/aldefy/compose-skill/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aldefy-compose-skill