compose-performance-skills ships 26 skills in a layout its own target cannot load

A skill is written for a model, not for you

The repository defines its own genre before describing its contents, and the definition is unusually blunt about the difference from documentation.

A skill is one Markdown file, with optional supporting material in a references directory beside it. It teaches an agent how to perform one focused task. It declares trigger vocabulary in frontmatter and a numbered workflow in the body. The agent reads the frontmatter, decides whether the skill applies to the task in front of it, and then follows the workflow step by step.

Then the part that matters if you are going to read or write one. A skill is not documentation for humans, it is operational instructions for a model, and that changes the voice: terse, imperative, correct and incorrect snippet pairs shown side by side, directives in capitals for what must and must not be done, and a verification checklist that proves the work was finished. Prose stays short and code samples carry the weight.

That is a different writing discipline from a tutorial. It also means the quality bar is different. A tutorial can be vague and still be useful to a person who already knows the domain, while an instruction file that is vague produces an agent that guesses.

The stated purpose follows from that framing: to give a coding agent enough operational knowledge to diagnose and fix a performance problem without guessing, and to give the developer reading the resulting diff a citation trail back to primary sources.

The nested layout does not load, so an install script symlinks it

Here is the packaging problem, stated plainly by the project itself.

The library holds 26 skills nested under category folders, so each one lives at a two-level path inside the repository. That structure is described as being for human readability.

The Claude Code skill loader, by contrast, expects each skill directly at a one-level path under its own skills directory. So a plain clone into that directory does not surface any of the skills, and the project attributes that finding to community feedback rather than to its own testing.

The resolution is a shell script. It clones the repository once to a stable location and then symlinks each individual skill folder into the expected 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

It is described as idempotent, it accepts a custom target directory as a positional argument, and it takes an uninstall flag that removes the symlinks it created.

After that you restart the agent. It then matches the trigger vocabulary in each skill's frontmatter against your prompt and loads the relevant file automatically.

So the install cost is a clone, a script invocation and a restart, and the update cost is a pull in the source clone with the symlinks still valid. That is a reasonable design, and it is also a sign that the skill ecosystem has not settled on one layout yet.

Two of the three documented agents ship extrapolated instructions

The repository documents install paths for three agent runtimes and is explicit about which of them have actually been tried.

One has been. The library is described as iterated against the coding agent whose file loader reads these files directly, where the skills load without adaptation.

The other two have not. For the Android Studio agent mode and for the assistant runtime, the documentation reasons by analogy: the official catalog and the first runtime both use a flat layout, and since the first runtime was found to require it, the expectation is that these will too. That is a reasonable inference and it is labelled as an expectation.

Then comes the disclosure. End-to-end behaviour with those two runtimes has not been independently verified by the author, and reports of working or broken integration are invited at the issue tracker.

So half the documented install paths are predictions. That is not unusual in a young ecosystem, and flagging it is better than not.

The install procedure for those two is also different in kind. Instead of a global directory, the repository is cloned inside your Android project under a dot-prefixed name chosen so you can ignore it in version control, and the script symlinks each skill into a project-local agent directory. The stated benefit is that updating is a single pull.

The official Android CLI cannot install this library

There is a natural command a reader would try first, and the documentation says up front that it will not work.

The official Android command-line tool manages skills, and it manages only the first-party catalog published by Google, taking a skill name as its argument. This repository is outside that catalog. It is a community library, and it is loaded by agent runtimes scanning project-local directories rather than installed through the tool.

That note is worth more than a convenience, because it establishes what kind of project this is. The first-party catalog is a curated, reviewed channel. A community library following the same file format is loaded by convention, and the convention is exactly what has not settled yet, as the two sections above show.

It also means the trust question is not the same as for a package from an index. There is nothing to install, nothing to execute except the symlink script, and nothing to audit beyond the text of the skills themselves. For a library whose entire content is instructions a model will follow, that is a reasonable trade: the failure mode of a bad skill is a bad suggestion in a diff you are reading, not code running on your machine.

The exception is the script, which is shell, runs on your machine, and is the one executable thing in a repository whose primary language is recorded as shell.

Nine categories, gerund slugs, and a hard line limit

The conventions are the most useful part of the repository for anyone extending it, and they are strict enough to be checkable.

A skill lives at a category directory containing a slug directory. There are nine permitted categories, covering stability, recomposition, lists, modifiers, side effects, measurement, build, audit and hot reload. Anything else is not a category.

The slug must be a gerund in lowercase hyphenated form, capped at sixty-four characters, and the two examples given are named for what you do rather than what the concept is: diagnosing a stability problem, migrating to a modifier node. The file itself is uppercase, and its body stays under five hundred lines, with anything longer pushed into the references directory.

That references directory is allowed exactly one level of nesting, and the reason given is not stylistic: deeper nesting breaks how agents preview the files. That is a constraint discovered from tool behaviour rather than imposed for tidiness.

Cross links between skills are relative Markdown links, so they resolve when the repository is browsed on a hosting site rather than only when an agent follows them.

Two navigation aids sit at the root: an index file that is a symptom-to-skill lookup table, which is the right entry point when you know what is wrong rather than what you need, and a full authoring specification in the documentation directory for anyone writing a new one.

Grounding is version-pinned, and the author's own projects count as sources

The provenance claim is specific enough to check.

Every skill is said to be grounded in primary sources, and the list is enumerated: the official Android developer documentation, the Compose compiler itself, posts by four named individuals, the author's own open source projects, and blog posts. Every API reference is pinned to a version.

That last part is the one that matters practically. Compose has changed enough across recent compiler releases that an unpinned recommendation can be actively wrong, so pinning is what makes the difference between a skill that helps and one that sends a model to a deprecated API. It is also what makes the library updatable without rewriting it.

Including the author's own libraries in the source list is worth noting neutrally rather than as an objection. Those projects are working Compose code written by someone who has shipped libraries, which is the kind of evidence the rest of the list is made of.

The final piece of the story sits outside the repository. There is no recorded homepage for the project, and the second section of the readme is a companion book that goes from how to use Compose into how it works, tracing the platform source through the compiler, the runtime and the user interface layer beneath each composable, with worked examples from that same body of libraries, and tying the layers together into performance work from stability inference through to the skip decision.

The book is described as updated for a specific Kotlin and a specific compiler version, which is a reminder that the skills lag or lead it depending on when they were last touched.

Editorial conclusion

This library suits an Android team that wants an agent to diagnose a slow composable from named sources rather than from intuition, and it is cheap to try because the install is a clone and a script. Read one SKILL.md file before installing anything, check that its API references match your compiler version, and decide whether you want symlinks into a global skills directory or a clone inside each project.

Frequently asked questions

Official sources

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