Kotlin Footguns, Mined from a 10.8k-Star App

What it does

kotlin-footguns is a corpus of standalone SKILL.md files in the open agent-skills format, readable by Claude Code and other coding agents without sacrificing human legibility. Each file documents a specific technique or domain—ranging from native JNA bindings and desktop packaging to Compose theming and Room migrations—and dedicates most of its space to Traps: concrete failure modes encountered in production, why they happen mechanically, and how to verify them against your own tree. The lessons were extracted from SimpMusic, a cross-platform music client in continuous production since April 2023 that ships to Android, Windows, macOS, and Linux.

The interesting bit

The verification pipeline is unusually adversarial: independent reviewers received only the skill files and the source tree, instructed to refute every claim rather than confirm them. By the final batches, every command in the “Verifying it” sections had to execute verbatim against the source tree before shipping, and mechanism claims were re-derived from bytecode disassembly and Kotlin stdlib sources rather than trusted from comments or changelogs.

Key highlights

• Skills span 14 groups plus two delta batches, covering everything from DSP chains and dual-player crossfade to desktop code-signing and CI.
• Every file is service-neutral: no third-party vendor names appear, so the patterns transfer to whichever API you are consuming.
• Files are kept between 60 and 140 lines so an agent can load them into context quickly.
• The corpus is explicitly mined from a production codebase, not written from documentation; the author notes every trap was paid for first in crash reports and failed releases.

Caveats

• The entire corpus is scoped to Kotlin, Compose Multiplatform, and desktop JVM; developers working outside this triangle will find little to reuse.
• The skills are debugging and architecture references, not beginner tutorials—they assume you are already shipping code against these APIs.

Verdict

Grab this if you are running Claude Code or another agent against a Kotlin multiplatform codebase and want to stop repeating production mistakes the documentation never warned you about. Skip it if you are not working with Kotlin, Compose, or the desktop JVM—this is domain-specific scar tissue, not generic wisdom.