kotlin-footguns README

The project's README from github.com/maxrave-dev/kotlin-footguns. As one markdown file: README.md.

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.

skills.sh SimpMusic stars GitHub followers Sponsor Buy Me a Coffee Blog License

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 SimpMusic repository on GitHub

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

Group Skills Focus
A 11 Native code on the desktop JVM: bindings, bundling, loading, memory
B 13 Desktop packaging, code signing, CI and build infrastructure
C 9 Multiplatform module structure, dependency injection, architecture
D 18 Media playback engine internals: players, crossfade, DSP, queues
E 11 Databases and SQL: sweeps, migrations, query traps at scale
F 7 Compose theming, palette extraction, gradients and scrims
G 11 Compose components and interaction patterns
H 8 Screens, navigation and adaptive layout
I 8 Reactive state: Flow, StateFlow, ViewModel lifecycles
J 7 Repository and data-layer patterns
K 8 Background work, services and platform runtime behavior
L 12 Consuming remote APIs: clients, parsing, auth flows, retries
M 10 Kotlin and multiplatform utilities and language traps
N 7 Engineering method: experiments, logs, changelogs, migrations
Δ6 76 Batch 6: sync rooms, equalizer and profile import, player style system, analytics, UI effects and platform lessons
Δ7 8 Batch 7: the v2.0.0 release sprint — word-timed lyrics, romanization, capture-to-image, story reel, on-demand assets

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:

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.

kotlin-footguns (maxrave-dev/kotlin-footguns)

Searching Database…

1.4K ·GitHub
Kotlin-footguns
What is this?A collection of 224 'agent skills' — markdown files mapping concrete failure modes ('footguns') in Kotlin, Compose Multiplatform and the desktop JVM, mined from a real production music app instead of written from documentation.
Is this a code library or a set of documentation files?It is a corpus of plain markdown files, one SKILL.md per skill, following the open agent-skills format. There is no runtime code to import; each file is readable by a coding agent or a human directly.
How do I add these skills to my project or agent?Two options: install the whole set as a managed, read-only Claude Code plugin updated with '/plugin marketplace update maxrave', or use the skills CLI (npx skills update) to copy editable skill files directly into your own project for any agent.
Which coding agents are supported besides Claude Code?The CLI installer lets you target Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini and others when copying skills into your repo.
Does installing both the plugin and the CLI version cause problems?Yes — the two installation paths are meant to be alternatives, not combined. Installing both just duplicates every skill.
Who is this really for?Developers building Kotlin / Compose Multiplatform / Android+desktop JVM apps who use coding agents (or just want a condensed engineering reference) and want to skip mistakes already paid for in a real shipped product.
What does the 'Traps' section of each skill actually contain?It's the dominant section of every file: the specific ways a technique fails in practice in real code, paired with a command to verify the failure on your own tree and the fix for it.
How was accuracy of 224 files actually checked?Each batch went through independent adversarial review lanes instructed to refute rather than confirm, with separate fix lanes whose repairs only counted once re-verified against the source tree; in the final batches every 'Verifying it' command had to be run verbatim before shipping.
Why mine lessons from a shipped app instead of writing from the docs?Official docs describe what an API is supposed to do; the author shipped SimpMusic against those APIs for years and recorded what actually broke — crashes, failed releases, wrong migrations — so every lesson here was already paid for in production before being written down.
Does any skill mention specific third-party services or vendors?No — the corpus is deliberately service-neutral; skills teach architecture and failure modes generically, and no service or vendor field names appear in any skill body.
What are similar projects?SpotiFlyer, operator-memory, skills, gkd, AppMarket, SwiftUI-Agent-Skill, skills, skills
Which topics is it in?compose-multiplatform, kotlin-multiplatform, jetpack-compose, android-development, jvm, agent-skill, best-practices, claude-skills, kotlin, knowledge-base, skills, documentation
Creator
maxrave-dev
Size
1.2 MB
Stars
1.4K
Updated
CommitOct 17
Age
1mo
Commits · 90 Days