kotlin-footguns

By maxrave-dev — creator and maintainer of
SimpMusic, the 10.8k-star cross-platform music app
every lesson in this repository was mined from.

224 battle-tested agent skills mapping the footguns of Kotlin, Compose Multiplatform and
desktop JVM development. Mined from a production codebase, not written from documentation.

Each skill is a standalone SKILL.md in the open agent-skills format, readable by Claude Code
and any coding agent that understands the format — and just as readable by a human. The corpus
is 27,000+ lines across 224 files, and in most of them the largest section is Traps: the
specific ways a technique fails in practice, each paired with a way to verify the failure and
the fix on your own tree.

Why this repository exists

Most agent-skill collections for Kotlin and Android are written from official documentation.
They tell an agent what the API is supposed to do. This repository records what happened when
its author shipped against those APIs for years: the API that reports success while discarding
your data, the build flag that means something different on one platform, the verification
step that passes on broken code, the migration that deleted the wrong thing first.

None of it is theory. Every lesson here is older than the document that describes it — each
one had already been paid for in crash reports, failed releases, review rounds and user-filed
issues before it was written down.

Where the lessons come from

The source is SimpMusic, a cross-platform music
client built with Kotlin and Compose Multiplatform, in continuous production since April 2023.
As of this writing it has earned more than 10,800 GitHub stars and 550 forks, and ships to
real users on Android, Windows, macOS and Linux through GitHub releases, F-Droid, IzzyOnDroid
and OpenAPK.

That codebase spans territory most sample projects never touch: a native media engine bound
over JNA, dual-player crossfade and DSP chains, a Room database at real-user scale, desktop
packaging and code-signing for three operating systems, CI that builds all of it, and a UI
written entirely in Compose. The skills are the distillation of that surface area.

The corpus itself is deliberately service-neutral. Skills teach architecture and failure
modes, never the mechanics of any third-party service; no service names or vendor field names
appear in any skill body. What was learned integrating specific services survives here as the
generic core that applies to whichever API you are consuming.

What is inside

The full annotated index, with one line per skill and its primary evidence, is in
CATALOG.md.

Anatomy of a skill

Every file follows the same discipline:

• Frontmatter — a name matching its folder and a description that states coverage,
  the trigger for reaching for it, and the symptom it explains.
• A short orientation — the working pattern, with code where code is clearer than prose.
• Traps — the dominant section: concrete failure modes, why each happens mechanically,
  and what to do instead.
• Verifying it — commands to run against your own codebase to confirm or rule out each
  claim. Quantities are expressed as commands you run rather than numbers that go stale.

Files are kept between 60 and 140 lines. A skill you cannot read in two minutes is a skill
an agent will not load in context.

How the corpus was verified

Extraction ran as a five-batch pipeline, and no file shipped as first drafted. Each batch was
reviewed by independent adversarial lanes that received only the files and the source tree —
never the author's reasoning — and were instructed to refute, not confirm. Findings were
repaired in separate fix lanes, and a repair was accepted only with the re-run evidence
attached. A follow-up delta batch, mined later from the source project's continued
development, went through the same pipeline at wider fan-out: ten write lanes, ten adversarial
verify lanes and seven fix lanes. A second delta batch, mined from the v2.0.0 release sprint,
ran four write lanes against two adversarial verify lanes and repaired every one of the
twenty-eight findings they raised — among them a published claim the reviewers refuted from the
dependency's own sources — with each repair re-verified against the tree before the batch merged.

The bar tightened as the project ran. By the final batches, every command in every
"Verifying it" section had to be executed verbatim against the source tree before shipping —
a stated outcome that could not be reproduced was itself a defect. Mechanism claims were
re-derived rather than trusted: bytecode disassembly against the pinned artifacts, Kotlin
stdlib sources, Python simulations of ported logic, and re-runs of the git history behind
every historical claim. Code comments, changelogs and commit messages were excluded as
evidence throughout; anything sourced only from prose is marked as such in the file.

In the final two batches alone this review raised close to thirty blocking findings — among
them verification steps that passed on defective code and prescribed fixes that did not fix
the case they named — every one repaired or refuted with recorded evidence before release. A
closing sweep re-checked all 216 files for identifier leaks, structural consistency and
cross-reference integrity, and confirmed the catalog matches the folders one to one in both
directions.

Installation

Two ways in, two philosophies. The Claude Code plugin installs the whole set as a managed,
read-only bundle that updates when this repository does — you subscribe rather than fork. The
skills CLI copies editable skill files into your own project, for any agent, so you can prune
and rewrite them. Pick one; installing both leaves you with every skill twice.

Claude Code, as a plugin

/plugin marketplace add maxrave-dev/kotlin-footguns
/plugin install kotlin-footguns@maxrave

Updates arrive with /plugin marketplace update maxrave.

Any agent, as editable files

npx skills@latest add maxrave-dev/kotlin-footguns

The installer lets you pick which of the 224 skills to take and which agents to install them
for — Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini and others. The files land in
your repository as ordinary markdown you own and can edit; nothing updates behind your back.
Pull newer versions when you want them with npx skills update.

Either way, each skill's description tells the agent when to load it, so installing many is
cheap: a skill enters context only when its trigger matches the work at hand. And because
every file is plain markdown built around traps and verification commands, the corpus reads
as an engineering reference without any agent at all.

About the author

I'm maxrave-dev. Since April 2023 I have built and maintained
SimpMusic from its first release to the v2.0.0 this corpus was mined against, shipping to real
users on Android, Windows, macOS and Linux, and I write the longer war stories up on the
SimpMusic blog. Every trap in these files is something I hit
in production first — the skills are the notes I wish I had at the time.

If this corpus saves you a debugging day, you can support the work through
GitHub Sponsors,
Buy Me a Coffee or
Liberapay.

License

GPL-3.0 for the whole repository, matching the source project. One skill,
custom-shuffle-order, adapts a design from Auxio's GPL-3.0 shuffle implementation and
carries its provenance note in the file.

Related

• SimpMusic — the source codebase
• simpmusic.org — the project site