kotlin-footguns: 224 agent skills mined from a shipping Kotlin app

What kotlin-footguns solves, and for whom

Documentation tells you what an API is supposed to do. It rarely tells you the API returns success while discarding your data, or that a build flag means something different on one platform, or that a verification step passes on broken code. kotlin-footguns is an attempt to capture that second category. The README states the corpus is "mined from a production codebase, not written from documentation," and the production codebase in question is SimpMusic, a cross-platform music client built with Kotlin and Compose Multiplatform that the README says has been in continuous production since April 2023 and ships to Android, Windows, macOS and Linux.

The intended reader is not a Kotlin beginner. It is someone running a coding agent over a Kotlin Multiplatform or Compose Desktop repository, or an engineer doing the same work by hand, who wants the agent to know where the sharp edges are before it writes code. The topics list confirms the framing: agent-skills, claude-code, compose-multiplatform, kotlin-multiplatform, android. If your project is a single-module Android app with no desktop target, no native bindings and no media engine, a large share of the corpus describes surface area you do not have.

The SKILL.md format and the discipline around it

Each skill is a standalone SKILL.md in what the README calls the open agent-skills format, readable by Claude Code and by any coding agent that understands the format. The repository README also says the files are readable by a human, and the structure supports that claim. Frontmatter carries a name matching its folder plus a description that states coverage, the trigger for reaching for the skill, and the symptom it explains. Then comes a short orientation, then Traps, which the README describes as the dominant section, then Verifying it.

Two design decisions are worth calling out. First, files are kept between 60 and 140 lines, with the stated rationale that "a skill you cannot read in two minutes is a skill an agent will not load in context." That is a hard budget, and it means depth is traded for loadability. Second, quantities are expressed as commands you run rather than numbers that go stale. A skill that says "this leaks" is less useful than one that says run this and watch the count. The README is explicit that by the final batches every command in every Verifying it section had to be executed verbatim against the source tree before shipping.

The corpus is also described as service-neutral: skills teach architecture and failure modes, and the README states no service names or vendor field names appear in any skill body. What was learned integrating specific services survives as the generic core. That is a deliberate editorial choice, and it costs you concrete examples in exchange for portability.

How the corpus is organised: groups A through N, plus two deltas

The README's table splits 224 skills into fourteen lettered groups and two delta batches. Groups A and B cover native code on the desktop JVM and desktop packaging, code signing, CI and build infrastructure. C through K run through multiplatform module structure, media playback internals, databases and SQL, Compose theming, Compose components, screens and navigation, reactive state with Flow and StateFlow, repository patterns, and background work. L covers consuming remote APIs. M covers Kotlin and multiplatform utilities and language traps. N is engineering method: experiments, logs, changelogs, migrations.

The two deltas are the interesting part for anyone judging recency. Δ6 is 76 skills covering sync rooms, equalizer and profile import, a player style system, analytics, UI effects and platform lessons. Δ7 is 8 skills mined from a v2.0.0 release sprint: word-timed lyrics, romanization, capture-to-image, story reel, on-demand assets. The README points to CATALOG.md for the full annotated index with one line per skill and its primary evidence. That file is the right entry point; the README table alone will not tell you which of 76 delta skills applies to your code.

Getting the files and reading your first skill

There is no package to install. The repository ships Markdown files plus a .claude-plugin directory, and the README gives no install command, no Gradle coordinate and no plugin marketplace instruction. The practical setup is to clone the repository and point your agent at the skills directory, or read the files directly.

The README names the files you will find at the top level, including CATALOG.md, README.md, LICENSE, the skills directory and a set of raw-*.md files. Work from that list rather than guessing at a layout.

.claude-plugin/
CATALOG.md
HANDOFF.md
LICENSE
README.md
assets/
pipeline-handoffs/
raw-core.md
raw-docs.md
raw-git.md
raw-handlers.md
raw-ui.md
skills/

Open CATALOG.md first. The README describes it as the full annotated index with one line per skill and its primary evidence, which is faster than browsing 224 folders.

CATALOG.md
skills/

Then read one skill end to end. Every skill folder contains a SKILL.md, and the Traps section is where the failure modes live. What you should see is frontmatter with a name and description, a short orientation, a Traps section, and a Verifying it section. If a file you open has no Verifying it section, treat its claims as unverified for your tree.

The verification pipeline, and what it does not promise

The README describes extraction as a five-batch pipeline in which no file shipped as first drafted. Each batch went through independent adversarial lanes that received only the files and the source tree, never the author's reasoning, and were instructed to refute rather than confirm. Findings were repaired in separate fix lanes, and a repair was accepted only with re-run evidence attached. The Δ6 batch ran ten write lanes, ten adversarial verify lanes and seven fix lanes. Δ7 ran four write lanes against two adversarial verify lanes and repaired all twenty-eight findings they raised, including a published claim the reviewers refuted from the dependency's own sources.

That is a stronger process than most skill collections describe, and it is also the source of the main limitation. The adversarial lanes worked against one source tree, SimpMusic. A trap that is real there may be absent in your code, and a trap that is real in your code may never have surfaced there. The README does not claim coverage of Kotlin or Compose as a whole, and nothing in it suggests the corpus is exhaustive. The Verifying it sections exist precisely because the reader is expected to confirm each claim locally rather than trust it.

There is a second gap: no releases are published for this repository. The README documents no versioning scheme and no changelog for the corpus itself, so there is no way to pin a specific revision of a skill and know what changed between pins. You get whatever the main branch holds.

Where it is the wrong tool

If you need something your build can depend on, this is not it. There is no artifact, no Gradle plugin, no published release, and the README describes no API. Everything is prose in Markdown, which means nothing fails your build when a skill goes stale.

If your codebase is far from SimpMusic's shape, the density drops fast. Groups A and B assume native bindings over JNA and desktop packaging with code signing for three operating systems. Groups D and E assume a media engine and a Room database at real-user scale. A Compose-only Android app with a REST backend will find group L and parts of G, H, I and J useful and most of the rest irrelevant. The README does not offer a recommended subset for narrower stacks.

Service neutrality is the third limitation, and it is self-imposed. Because no service names or vendor field names appear in any skill body, an integration lesson arrives stripped of the API that produced it. You get the generic retry or auth-flow failure mode, not the field name that broke. Whether that is a feature or a loss depends on how much you value portability over a worked example.

kotlin-footguns versus a conventional Kotlin style guide

The natural comparison is a community style guide or a static analysis ruleset. Those encode conventions: naming, formatting, forbidden constructs. They are enforced by a linter and they fire on every build. Their weakness is that a rule which passes the linter can still lose data at runtime, and a style guide has no mechanism for expressing "this API reports success while discarding your data."

kotlin-footguns inverts the priority. It does not care about formatting and it does not run in your build. It cares about failure modes that survive review, and it pairs each one with a command you run against your own tree to confirm the failure is real. The difference in approach is enforcement versus evidence. A linter tells you a line is wrong; a skill tells you a pattern is wrong and how to prove it on your code.

The trade-off is real. A linter gives a binary answer on every commit. A skill gives a probabilistic nudge to an agent that may or may not load it, and its verification step only helps if a human or agent actually runs it. The README's line-length budget exists because of that uncertainty, and it is an admission that attention is the scarce resource.

Licence, maintenance and what an upgrade costs

The repository is GPL-3.0. If you copy SKILL.md text into your own repository, into a product, or into a commercial agent configuration, the copyleft terms of that licence apply to what you redistribute. Reading the files and acting on them is a different question from republishing them, and the README does not discuss either case. This is not legal advice; if the files are going into a shipped product, have someone qualified read the licence.

The maintenance picture is concrete. The repository is not archived, and the last push was on 2026-08-29. There are no releases. Upgrading means pulling main and re-reading whichever files you actually loaded, since there is no changelog for the corpus and no version boundary to diff against. The cost of an upgrade is therefore proportional to how many skills you wired into a workflow, and that cost is paid in reading time, not in a dependency bump.

One structural detail helps here: the raw-*.md files and pipeline-handoffs directory sit at the top level next to skills. They are not described in the README as part of the shipped corpus, so treat them as working material rather than as skills to load.

Editorial conclusion

Adopt kotlin-footguns if you maintain a Kotlin Multiplatform or Compose Desktop codebase and want your coding agent to carry failure modes rather than API summaries; the Traps sections and the command-based Verifying it steps are the part worth loading. Skip it if you need a library, a Gradle plugin or per-version compatibility guarantees, because this repository ships prose files and nothing else. Before wiring it into a workflow, open CATALOG.md and locate the group that matches your stack, then read one SKILL.md end to end and run its verification command against your own tree; if that command does not reproduce anything on your code, the skill is not describing your code.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. maxrave-dev/kotlin-footguns on GitHub
4. README