Skip to content
Back to search

maxrave

Agent skills by maxrave-dev, distilled from shipping SimpMusic in production since 2023.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maxrave-dev--kotlin-footguns/badge.svg)](/listings/maxrave-dev--kotlin-footguns)

HTML

<a href="/listings/maxrave-dev--kotlin-footguns"><img src="/api/listings/maxrave-dev--kotlin-footguns/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 eleven skills (ten areas and the scanner) 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, only eleven short descriptions sit in the agent's context on every turn. An area's index loads when the work touches that area, and a trap's file only when it applies. 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "maxrave",
  3. "owner": {
  4. "name": "maxrave-dev",
  5. "url": "https://simpmusic.org"
  6. },
  7. "description": "Agent skills by maxrave-dev, distilled from shipping SimpMusic in production since 2023.",
  8. "plugins": [
  9. {
  10. "name": "kotlin-footguns",
  11. "source": "./",
  12. "description": "228 battle-tested traps mapping the footguns of Kotlin, Compose Multiplatform and desktop JVM development, in ten area skills plus a scanner — mined from a production codebase, every claim verified against the real tree.",
  13. "category": "engineering",
  14. "keywords": [
  15. "kotlin",
  16. "compose-multiplatform",
  17. "android",
  18. "desktop-jvm",
  19. "footguns",
  20. "skills"
  21. ]
  22. }
  23. ]
  24. }
README.md · README · 222 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # kotlin-footguns
  2. **By [maxrave-dev](https://github.com/maxrave-dev)** — creator and maintainer of
  3. [SimpMusic](https://github.com/maxrave-dev/SimpMusic), the 10.8k-star cross-platform music app
  4. every lesson in this repository was mined from.
  5. [![skills.sh](https://skills.sh/b/maxrave-dev/kotlin-footguns)](https://skills.sh/maxrave-dev/kotlin-footguns)
  6. [![SimpMusic stars](https://img.shields.io/github/stars/maxrave-dev/SimpMusic?style=flat&logo=github&label=SimpMusic)](https://github.com/maxrave-dev/SimpMusic)
  7. [![GitHub followers](https://img.shields.io/github/followers/maxrave-dev?style=flat&logo=github&label=Followers)](https://github.com/maxrave-dev)
  8. [![Sponsor](https://img.shields.io/badge/GitHub_Sponsors-%E2%9D%A4-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/maxrave-dev)
  9. [![Buy Me a Coffee](https://img.shields.io/badge/Buy_Me_a_Coffee-%E2%98%95-FFDD00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/maxrave)
  10. [![Blog](https://img.shields.io/badge/Blog-simpmusic.org-4B8BBE?logo=rss&logoColor=white)](https://www.simpmusic.org/blogs)
  11. [![License](https://img.shields.io/badge/License-GPL--3.0-blue)](LICENSE)
  12. 228 battle-tested traps mapping the footguns of Kotlin, Compose Multiplatform and desktop JVM
  13. development, packaged as ten agent skills plus a scanner that checks a change against them. Mined
  14. from a production codebase, not written from documentation.
  15. The traps are grouped into ten area skills in the open agent-skills format, readable by Claude
  16. Code and any coding agent that understands the format — and just as readable by a human. Each
  17. area skill is an index of its traps; each trap is a standalone markdown file the agent opens
  18. when the work in front of it matches. The corpus is 28,000+ lines across 228 files, and in most
  19. of them the largest section is **Traps**: the
  20. specific ways a technique fails in practice, each paired with a way to verify the failure and
  21. the fix on your own tree.
  22. ## Why this repository exists
  23. Most agent-skill collections for Kotlin and Android are written from official documentation.
  24. They tell an agent what the API is supposed to do. This repository records what happened when
  25. its author shipped against those APIs for years: the API that reports success while discarding
  26. your data, the build flag that means something different on one platform, the verification
  27. step that passes on broken code, the migration that deleted the wrong thing first.
  28. None of it is theory. Every lesson here is older than the document that describes it — each
  29. one had already been paid for in crash reports, failed releases, review rounds and user-filed
  30. issues before it was written down.
  31. ## Where the lessons come from
  32. ![The SimpMusic repository on GitHub](assets/simpmusic-github-header.png)
  33. The source is [SimpMusic](https://github.com/maxrave-dev/SimpMusic), a cross-platform music
  34. client built with Kotlin and Compose Multiplatform, in continuous production since April 2023.
  35. As of this writing it has earned more than 10,800 GitHub stars and 550 forks, and ships to
  36. real users on Android, Windows, macOS and Linux through GitHub releases, F-Droid, IzzyOnDroid
  37. and OpenAPK.
  38. That codebase spans territory most sample projects never touch: a native media engine bound
  39. over JNA, dual-player crossfade and DSP chains, a Room database at real-user scale, desktop
  40. packaging and code-signing for three operating systems, CI that builds all of it, and a UI
  41. written entirely in Compose. The traps are the distillation of that surface area.
  42. The corpus itself is deliberately service-neutral. The traps teach architecture and failure
  43. modes, never the mechanics of any third-party service; no service names or vendor field names
  44. appear in any trap file. What was learned integrating specific services survives here as the
  45. generic core that applies to whichever API you are consuming.
  46. ## What is inside
  47. | Area skill | Traps | Focus |
  48. |---|---|---|
  49. | [`desktop-and-build-footguns`](skills/desktop-and-build-footguns/SKILL.md) | 24 | Native code on the desktop JVM; desktop packaging, code signing, CI and build |
  50. | [`kmp-architecture-footguns`](skills/kmp-architecture-footguns/SKILL.md) | 25 | Multiplatform module structure, dependency injection, architecture; Kotlin language traps |
  51. | [`media-playback-footguns`](skills/media-playback-footguns/SKILL.md) | 33 | Players and crossfade, audio processing and DSP, queues, shared listening sessions |
  52. | [`data-layer-footguns`](skills/data-layer-footguns/SKILL.md) | 26 | Room and SQL at scale, migrations, repositories, caching and paging |
  53. | [`compose-visuals-footguns`](skills/compose-visuals-footguns/SKILL.md) | 36 | Theming and colour, gradients and scrims, effects and animation, charts |
  54. | [`compose-screens-footguns`](skills/compose-screens-footguns/SKILL.md) | 32 | Screens, navigation, adaptive layout, components and interaction |
  55. | [`state-and-background-footguns`](skills/state-and-background-footguns/SKILL.md) | 23 | Flow, StateFlow and ViewModel lifecycles; background work, services, platform runtime |
  56. | [`webview-footguns`](skills/webview-footguns/SKILL.md) | 3 | WebView on low-RAM phones and provider-less devices: startup, renderer death, AndroidView lifecycle, cookies |
  57. | [`remote-api-footguns`](skills/remote-api-footguns/SKILL.md) | 17 | Clients and parsing, auth and retries, realtime sessions and wire protocols |
  58. | [`engineering-method-footguns`](skills/engineering-method-footguns/SKILL.md) | 9 | Experiments, build logs, commit history, changelogs, removing a feature |
  59. Each area skill lists its traps under headings, each with the description that tells an agent
  60. when to open it. The whole index on one page is [CATALOG.md](CATALOG.md). An eleventh skill,
  61. [`footgun-scan`](skills/footgun-scan/SKILL.md), checks code against the traps (below).
  62. ## Why ten skills and not 228
  63. Until version 2.0 every trap was its own skill, and the set crowded out everything else in the
  64. agent's skill listing. Claude Code lists every installed skill's name and description on every
  65. turn, inside a budget of 1% of the context window (8,000 characters for a 200K-token window),
  66. and lists whatever does not fit by name alone, least-used first. The 224 descriptions came to
  67. about 124,000 characters and the names alone to 7,500, so at that budget every trap reached the
  68. agent as a bare name, and so did every other skill the user had installed, their own included.
  69. As ten area skills plus the scanner the listing is about 2,900 characters. The agent loads an area's index when
  70. the work touches that area, sees every trap in it at once with the symptom that should send it to
  71. each one, and opens only the files that apply.
  72. ## Scanning a change
  73. `footgun-scan` turns the traps into a check. It matches 32 patterns against the lines a change
  74. adds; each pattern is tied to one trap, and the agent opens that trap to confirm or dismiss every
  75. hit. Ask for it in plain words ("check my uncommitted Kotlin changes for footguns"), or run the
  76. script yourself, for example as a CI step:
  77. ```bash
  78. python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --fail
  79. ```
  80. A hit is `likely` when the shape is wrong unless the exception its trap names holds, and `look`
  81. when it marks a place the trap says to inspect. Over the whole of SimpMusic and its core module the
  82. scanner raised 26 `likely` hits, and all 26 matched their trap on inspection: 22 vertical slides
  83. left at their half-height default, two fades from `Color.Transparent` into a colour, and two values
  84. spliced into migration SQL. The `look` hits are places to read, not verdicts.
  85. ## Does it help?
  86. [`evals/`](evals/README.md) holds thirteen `claude plugin eval` cases, each run with the plugin and
  87. without it. With it, all twelve trap questions passed in every run and the agent opened the right
  88. trap file every time. Without it they averaged 0.56. On five of them the model already knew the
  89. lesson. On four it was confidently wrong: it described a Room connection-routing rule and a
  90. resource formatter that do not exist. The full table and its caveats are in
  91. [evals/README.md](evals/README.md).
  92. ## Anatomy of a trap
  93. Every trap file follows the same discipline:
  94. - **Frontmatter** — a `name` matching its file name and a `description` that states coverage,
  95. the trigger for reaching for it, and the symptom it explains. The area index repeats that
  96. description, so the agent chooses on exactly this text.
  97. - **A short orientation** — the working pattern, with code where code is clearer than prose.
  98. - **Traps** — the dominant section: concrete failure modes, why each happens mechanically,
  99. and what to do instead.
  100. - **Verifying it** — commands to run against your own codebase to confirm or rule out each
  101. claim. Quantities are expressed as commands you run rather than numbers that go stale.
  102. Files are kept between 60 and 140 lines. A trap you cannot read in two minutes is a trap an
  103. agent will not load in context.
  104. The area indexes and CATALOG.md are generated: after adding or editing a trap, run
  105. `python3 scripts/build_index.py`. It refreshes every index line from the trap's own description,
  106. fails if a file is unlisted, listed twice or missing, or if a cross-reference names a trap that
  107. does not exist, and reports how much of the listing budget the skills take. Add `--check`
  108. to verify without writing.
  109. ## How the corpus was verified
  110. Extraction ran as a five-batch pipeline, and no file shipped as first drafted. Each batch was
  111. reviewed by independent adversarial lanes that received only the files and the source tree —
  112. never the author's reasoning — and were instructed to refute, not confirm. Findings were
  113. repaired in separate fix lanes, and a repair was accepted only with the re-run evidence
  114. attached. A follow-up delta batch, mined later from the source project's continued
  115. development, went through the same pipeline at wider fan-out: ten write lanes, ten adversarial
  116. verify lanes and seven fix lanes. A second delta batch, mined from the v2.0.0 release sprint,
  117. ran four write lanes against two adversarial verify lanes and repaired every one of the
  118. twenty-eight findings they raised — among them a published claim the reviewers refuted from the
  119. dependency's own sources — with each repair re-verified against the tree before the batch merged.
  120. The bar tightened as the project ran. By the final batches, every command in every
  121. "Verifying it" section had to be executed verbatim against the source tree before shipping —
  122. a stated outcome that could not be reproduced was itself a defect. Mechanism claims were
  123. re-derived rather than trusted: bytecode disassembly against the pinned artifacts, Kotlin
  124. stdlib sources, Python simulations of ported logic, and re-runs of the git history behind
  125. every historical claim. Code comments, changelogs and commit messages were excluded as
  126. evidence throughout; anything sourced only from prose is marked as such in the file.
  127. In the final two batches alone this review raised close to thirty blocking findings — among
  128. them verification steps that passed on defective code and prescribed fixes that did not fix
  129. the case they named — every one repaired or refuted with recorded evidence before release. A
  130. closing sweep after the first delta batch re-checked all 216 files then in the corpus for
  131. identifier leaks, structural consistency and cross-reference integrity, and confirmed the catalog
  132. matches the files one to one in both directions — a check `scripts/build_index.py` now repeats
  133. on every run.
  134. ## Installation
  135. Two ways in, two philosophies. The Claude Code plugin installs the whole set as a managed,
  136. read-only bundle that updates when this repository does — you subscribe rather than fork. The
  137. skills CLI copies editable skill files into your own project, for any agent, so you can prune
  138. and rewrite them. Pick one; installing both leaves you with every skill twice.
  139. ### Claude Code, as a plugin
  140. ```
  141. /plugin marketplace add maxrave-dev/kotlin-footguns
  142. /plugin install kotlin-footguns@maxrave
  143. ```
  144. Updates arrive with `/plugin marketplace update maxrave`.
  145. ### Any agent, as editable files
  146. ```bash
  147. npx skills@latest add maxrave-dev/kotlin-footguns
  148. ```
  149. The installer lets you pick which of the eleven skills (ten areas and the scanner) to take and which
  150. agents to install them for — Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini and others. The files land in
  151. your repository as ordinary markdown you own and can edit; nothing updates behind your back.
  152. Pull newer versions when you want them with `npx skills update`.
  153. Either way, only eleven short descriptions sit in the agent's context on every turn. An area's
  154. index loads when the work touches that area, and a trap's file only when it applies. And because
  155. every file is plain markdown built around traps and verification commands, the corpus reads
  156. as an engineering reference without any agent at all.
  157. ## About the author
  158. I'm [maxrave-dev](https://github.com/maxrave-dev). Since April 2023 I have built and maintained
  159. SimpMusic from its first release to the v2.0.0 this corpus was mined against, shipping to real
  160. users on Android, Windows, macOS and Linux, and I write the longer war stories up on the
  161. [SimpMusic blog](https://www.simpmusic.org/blogs). Every trap in these files is something I hit
  162. in production first — the skills are the notes I wish I had at the time.
  163. If this corpus saves you a debugging day, you can support the work through
  164. [GitHub Sponsors](https://github.com/sponsors/maxrave-dev),
  165. [Buy Me a Coffee](https://www.buymeacoffee.com/maxrave) or
  166. [Liberapay](https://liberapay.com/maxrave).
  167. ## License
  168. GPL-3.0 for the whole repository, matching the source project. One skill,
  169. `custom-shuffle-order`, adapts a design from Auxio's GPL-3.0 shuffle implementation and
  170. carries its provenance note in the file.
  171. ## Related
  172. - [SimpMusic](https://github.com/maxrave-dev/SimpMusic) — the source codebase
  173. - [simpmusic.org](https://simpmusic.org) — the project site

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.