compose-performance-skills: Agent Skills for Jetpack Compose Performance

The gap this library fills: Compose performance knowledge an agent can load on demand

The README frames the project against android/skills, Google's first party Agent Skill catalog. That catalog covers Android development at large. This repository goes narrow: Jetpack Compose performance only. The categories listed in the directory layout are stability, recomposition, lists, modifiers, side-effects, measurement, build, audit and hot-reload, and the README says the library holds 26 skills.

The audience is narrow too. A Skill is, in the README's words, "operational instructions for an LLM," not documentation for humans. So the person who benefits is the developer running a coding agent against a Compose codebase and wanting the agent to reason about skip decisions, stability inference and lazy layout costs instead of guessing. The README also claims a citation trail back to primary sources: Android Developers documentation, the Compose compiler, posts by Ben Trengrove, Chris Banes and Manuel Vivo, the skydoves open source projects, and blog posts, with API references pinned to a version.

That citation promise is the interesting part. Most agent guidance is prose the model absorbs without provenance. Here the claim is that each skill can be traced. Whether every skill lives up to it is something you can check by opening a SKILL.md and following its references.

How a SKILL.md is structured and how the agent decides to load it

Each skill is one Markdown file plus optional references. The README describes the mechanism precisely: the file declares trigger vocabulary in YAML frontmatter and a numbered workflow in the body. The agent reads the frontmatter, decides whether the skill applies to the current task, then follows the workflow step by step. Nothing is executed by the skill itself; it is context the runtime pulls in.

The writing conventions follow from that. The README says the voice is terse and imperative, with RIGHT and WRONG snippet pairs, MUST and MUST NOT directives in bold caps, and a Verification checklist that proves the work was done. Prose stays short and code samples carry the load. If you have read agent-facing documentation before, this is the same register: instructions, not explanation.

The repository layout is opinionated in ways that matter for loading. Skills live at `<category>/<slug>/SKILL.md`, with categories such as `stability` or `lists` and gerund slugs like `diagnosing-compose-stability`. Each skill body stays under 500 lines, and longer material moves into `references/`, which is allowed one level deep only. The README states that deeper nesting breaks how agents preview the files. Cross links between skills are relative Markdown links so they resolve when browsing on GitHub.

The full authoring specification is in docs/SPEC.md, which is the document to read if you intend to contribute a skill rather than consume one.

Installing the skills for Claude Code with scripts/install-skills.sh

The README is explicit that a plain clone will not work for Claude Code. That loader expects each skill at `~/.claude/skills/<slug>/SKILL.md`, but this repository nests skills under category folders for human readability. The README notes that community feedback confirmed the plain clone does not surface the skills. The bundled script clones once to a stable location and symlinks each individual skill folder into the loader's directory.

git clone https://github.com/skydoves/compose-performance-skills.git \
  ~/.claude/skills-sources/compose-performance-skills

~/.claude/skills-sources/compose-performance-skills/scripts/install-skills.sh

The README says the script is idempotent and accepts an optional custom target directory. To point it somewhere else, or to remove what it created:

./scripts/install-skills.sh /path/to/agent/skills      # custom target
./scripts/install-skills.sh --uninstall                # remove the symlinks

After the symlinks exist, restart Claude Code. A prompt that mentions a Compose performance symptom should match the trigger vocabulary in the frontmatter, and the relevant SKILL.md loads automatically. The README gives concrete examples: a slow LazyColumn should trigger `optimizing-lazy-layouts`, a stability question should trigger `diagnosing-compose-stability`.

For Android Studio Agent mode and Gemini, the README says those agents scan project local directories at runtime per Google's Android skills documentation, and that the official catalog uses a flat layout. Based on the Claude Code feedback, it expects the same flat requirement, so the same script is used against a project local target:

cd <your-android-project>
git clone https://github.com/skydoves/compose-performance-skills.git \
  .compose-performance-skills-source

./.compose-performance-skills-source/scripts/install-skills.sh .agent/skills

The source repository sits at `.compose-performance-skills-source/` so it can be gitignored and updated with a single `git pull`. The README states plainly that end to end behavior with Android Studio Agent mode and Gemini has not been independently verified by the author, and that other compatible runtimes have not been individually tested.

The Android CLI boundary and why this is not an `android skills add` package

One constraint deserves its own section because it trips people up. The README notes that the Android CLI manages only Google's first party skill catalog, installed with `android skills add --skill <name>`. This repository is a community library outside that catalog. It is loaded by agent runtimes from project local directories rather than installed through the CLI.

So there is no `android skills add` path here, and no versioned release to pin. The repository has no releases retrieved, and updates arrive as commits on `main`. The last push was on 2026-06-16. That is recent enough that the project is not stale, but the update mechanism for a consumer is a `git pull` in the clone directory followed by re-running the install script if the skill set changed.

This also means discovery is your runtime's problem, not a package manager's. If your agent does not scan the directory you installed into, the skills are invisible no matter how good they are.

What the README does not settle: verification, versioning and the missing measurement loop

The README lists measurement as one of the categories and describes "the measurement loop that ties them together" as part of the library's scope. What the README does not document is a way for a reader to reproduce that loop: there is no sample project, no benchmark harness, and no recorded baseline in the repository. The claim is that the skills teach an agent to measure; the evidence for the measurement approach has to come from the individual SKILL.md files, which the README does not reproduce.

Version pinning is similarly asserted rather than demonstrated. The README says every API reference is pinned to a version, and that the companion book is updated for Kotlin 2.4.0 and Compose Compiler 2.4.0. It does not say which Compose or Kotlin versions the skills themselves assume, and with no releases there is no changelog to check against a project running an older compiler. If you are on a Compose compiler a couple of years behind, the guidance may describe behavior your build does not have.

The runtime coverage is the third gap. Claude Code is the runtime the README says the library was iterated against. Android Studio Agent mode and Gemini are described as expected to work based on that experience, with the author stating they were not independently verified. If your team standardizes on one of those, you are the test.

None of this is unusual for a young community library, but it changes how you should evaluate it. Read a skill before trusting it, and check its pinned references against your build.

How it compares to android/skills and to reading the Compose compiler docs yourself

The obvious alternative is android/skills, Google's first party catalog. The difference is scope and distribution. android/skills covers Android development broadly and is managed by the Android CLI, so installation and updates go through `android skills add`. This repository covers one axis, Compose performance, and installs by cloning and symlinking. If you want breadth and a managed update path, the first party catalog is the fit. If you want depth on skip decisions, stability inference and lazy layout costs, the narrow library is the fit, at the cost of doing your own updates.

The second alternative is not a library at all: read the Compose compiler documentation and the posts the README cites, and write your own project local skill. That is more work and it is the honest comparison, because the value here is curation and packaging, not secret knowledge. The README names its sources openly, so a team with a strong Compose performance owner could reproduce the substance. What they would not get for free is the trigger vocabulary, the numbered workflows, and the RIGHT and WRONG pairs tuned for an agent to follow.

The companion book, Jetpack Compose Mechanisms, sits in a different slot. It is human-facing material tracing the AOSP source through the compiler, runtime and UI layers. The skills are the agent-facing artifact; the book is the explanation. They are complements, and the README links them.

Licence, maintenance and the cost of keeping skills in sync

The repository is Apache-2.0, and the LICENSE file sits at the top level alongside README.md and INDEX.md. Apache-2.0 permits commercial use and modification with the usual notice and attribution conditions; if you fork the skills into an internal repository, keep the licence file and check the NOTICE requirements with your own counsel rather than assuming. Nothing in the README adds terms beyond the licence.

Maintenance cost falls into two buckets. The first is updating: the repository has no releases, so your clone tracks `main`, and a `git pull` in the source directory followed by re-running `scripts/install-skills.sh` refreshes the symlinks. The script's idempotence makes that cheap, and `--uninstall` gives you a clean removal path if you decide the library is not earning its place.

The second bucket is drift. Because skills pin API references to versions, a skill written for one Compose compiler generation can describe skip behavior your build no longer has. The repository does not ship a compatibility matrix, so the check is manual: open the skills you actually rely on after a compiler upgrade and confirm the referenced behavior still matches. That is the recurring cost of this approach, and it is the reason a small library you have read beats a large one you have not.

Editorial conclusion

Adopt this library if you already run Claude Code or another agent runtime that loads SKILL.md files from a local directory and you want Compose performance guidance the agent can cite back to primary sources. Do not adopt it if you need a CLI-installed catalog entry, a human tutorial, or verified integration with a runtime the author has not tested. Before wiring it into a project, clone the repository, read docs/SPEC.md and one skill end to end, and confirm your runtime discovers SKILL.md at the flat depth the install script produces. The repository's own README is the authority on what has and has not been tested; treat the untested runtimes as untested.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. skydoves/compose-performance-skills on GitHub