Kotlin Footguns
228 battle-tested Kotlin, Compose Multiplatform and desktop JVM traps, packaged as agent skills an AI coding agent loads on demand.
- Source repo
- maxrave-dev/kotlin-footguns
- Stars
- ★ 1.9k
- Last updated
- 7d ago
- License
- GPL-3.0
- Primary language
- Python
- FA score
- 50/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude CodeChatGPT · Claude.ai (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An individual writing Compose Multiplatform UI in Claude Code or Cursor who wants to avoid gradient, scrim and animation parameter mistakes.
- Not a fit if
- Teams not on Kotlin, Compose Multiplatform or desktop JVM
- Anyone wanting a general-purpose linter across any language
- Teams requiring a vendor-hosted service with an SLA
- Source review
- 50/100 · Major gaps
What does this agent do, and when should you use it?
Kotlin Footguns is a skills corpus for coding agents, written entirely in Markdown, about the ways Kotlin, Compose Multiplatform and desktop JVM work actually fails. It holds 228 trap files across more than 28,000 lines, grouped into ten area skills (desktop-and-build, kmp-architecture, media-playback, data-layer, compose-visuals, compose-screens, state-and-background, webview, remote-api, engineering-method) plus an eleventh scanner skill, footgun-scan. Each area skill is an index: the agent loads it only when the current work touches that area, reads the symptom list, then opens the individual trap file that applies — keeping the always-on context at roughly 2,900 characters instead of 228 separate skill listings. Every trap file follows the same shape: frontmatter, a short orientation, a dominant Traps section covering concrete failure modes and fixes, and a Verifying it section with commands to run against your own tree. The bundled footgun-scan script matches 32 patterns against added lines and can gate a CI step. Two install paths exist: a managed read-only Claude Code plugin, or npx skills to copy editable Markdown into your own project for Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini and others.
All content lives under skills/ as eleven skill directories; each area is a SKILL.md index listing its traps with the description that tells an agent when to open one, next to standalone trap Markdown files. At runtime only eleven short descriptions sit in context each turn; when a task lands in an area the agent loads that index, sees every trap symptom at once, and opens only the matching files. Trap files explain the mechanical cause of each failure, the fix, and a Verifying it section with commands to run against your codebase instead of numbers that go stale. The footgun-scan skill ships .claude/skills/footgun-scan/scripts/scan.py, which matches 32 patterns (each bound to one trap) against the lines a change adds and labels hits likely or look; it runs in CI with python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --fail, and the agent then opens the linked trap to confirm or dismiss each hit. scripts/build_index.py regenerates the area indexes and CATALOG.md from each trap's own description, supports --check, and fails on unlisted, duplicated or missing files and broken cross-references. The evals/ directory holds thirteen claude plugin eval cases run with and without the plugin.
- An individual writing Compose Multiplatform UI in Claude Code or Cursor who wants to avoid gradient, scrim and animation parameter mistakes.
- A developer maintaining a multi-module KMP project who needs lower risk in Room migrations, repositories and caching layers.
- A release owner packaging a desktop JVM app for three operating systems who wants the signing and CI pitfalls up front.
- A team adding footgun-scan to CI so each PR's added Kotlin lines are checked against known failure modes before merge.
- An engineer who wants a production-mined Kotlin/Compose reference to read without any agent involved.
- A team that wants skill files checked into its own repository and pruned to fit its codebase, via npx skills.
How do you install or deploy this agent?
As a Claude Code plugin (managed, read-only, updates with the repository):
/plugin marketplace add maxrave-dev/kotlin-footguns
/plugin install kotlin-footguns@maxravePull updates with:
/plugin marketplace update maxraveOr copy editable skill files into your own project for any supported agent (Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini and others):
npx skills@latest add maxrave-dev/kotlin-footgunsLater updates:
npx skills updatePick one path only; installing both leaves every skill present twice. Running scan.py needs Python 3; the npx path needs Node.js.
How do you use this agent?
Ask the agent in plain words to check your uncommitted Kotlin changes for footguns, or run the scanner yourself, for example as a CI step:
python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --failA likely hit is wrong-shaped code unless the exception its trap names holds; a look hit marks a place the trap says to inspect. After adding or editing a trap, rebuild the generated indexes:
python3 scripts/build_index.pyTo verify without writing:
python3 scripts/build_index.py --checkWhat are this agent's strengths and limitations?
- Every lesson is mined from SimpMusic, a Kotlin/Compose Multiplatform app in production since April 2023 with 10.8k+ stars, not paraphrased from official docs.
- Area-index loading keeps the always-on footprint near 2,900 characters, sidestepping the 1% skill-listing budget that 228 separate skills would exhaust.
- Each trap ends with Verifying it commands that run against the reader's own tree, so claims are checkable rather than advisory.
- footgun-scan converts the corpus into 32 executable patterns and can fail a CI job on added lines.
- Two documented install paths (Claude Code plugin marketplace, npx skills) and plain Markdown throughout, so it reads as an engineering reference without any agent.
- Thirteen plugin evals are published with and without the plugin, including the cases where the model already knew the answer or was confidently wrong.
- Strictly scoped to Kotlin, Compose Multiplatform, Android and desktop JVM; no value outside that stack.
- The scanner is only 32 patterns over clearly shaped lines, so misses and false positives still require opening trap files to judge.
- Area indexes and CATALOG.md are generated; hand edits are overwritten and new traps must follow the naming and frontmatter conventions.
- The documented verification pipeline (adversarial review lanes, verbatim command re-runs) reflects the author's workflow and is hard for another team to replicate.
- Updates depend on the author's marketplace or on Node.js and npx, and running both install paths duplicates skills.
- No hosted service, SLA or versioned release process is documented beyond marketplace updates.
How does this agent compare with similar options?
The README contrasts the corpus only with the generic practice of writing Kotlin/Android agent skills from official documentation; it names no competing skill collection or Kotlin static-analysis product, so no specific alternative is compared.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Kotlin Footguns This agent | 50 · Major gaps | Agent plugin / skillFree | ★ 1.9k | 7d ago | Python | Codex · Claude Code |
| Aurite Agent Verifier | 52 · Major gaps | Agent plugin / skillFree | ★ 44 | 23d ago | — | Codex · Claude Code |
| Argot Repository Style Analyzer | 93 · Excellent | CLIFree | ★ 52 | 2mo ago | Rust | Claude Code |
| Jev Review | 81 · Good | Agent plugin / skillFree + model costs | ★ 248 | 1mo ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The repository is mostly Markdown skills plus one Python scanner; the README states the scanner only reads added lines and matches 32 patterns, with no declared network access, credential reads, or destructive defaults, so the permission surface looks small. However, the README alone cannot confirm the script's actual behavior, and installation routes through third-party channels (npx skills, /plugin marketplace) whose data flow and update mechanics are not documented in-repo, so each trust criterion is scored 1. source_attribution is stronger: the author, the SimpMusic source project, GPL-3.0 licensing, and the Auxio-derived custom-shuffle-order provenance note are all stated, earning 2.
The README gives a fairly concrete and internally consistent account of skill counts, trap counts, and the build_index.py consistency checks (fails on unlisted, duplicated, missing, or dangling cross-references), earning 2. Dependencies (npx skills, claude plugin eval, skills.sh badge) are neither pinned nor described for availability, and failure messaging is limited to the scanner's likely/look distinction with no shown error handling, so those are 1 each.
The README clearly defines audience (Kotlin/Compose Multiplatform/desktop JVM developers and coding agents), scenarios (ten area skills plus a scanner), and triggering (area index loads on relevant work, trap files open by description match), and explains the consolidation from 228 skills to ten for context-budget reasons, earning 2. No adaptation details or fallbacks for differing agent environments are given, so not 3.
Information architecture is clear (CATALOG.md, ten area indexes, uniform trap file structure, generator script); install notes give two paths with an explicit warning not to install both; naming rules (frontmatter name matching filename) are stated; the full GPL-3.0 text is present — all 2. Examples are scattered commands with no FAQ, known limitations are limited to context budget and the scanner's non-verdict look hits, versioning appears only as an in-text v2.0 mention with no CHANGELOG, and maintenance responsibility rests on an author self-description with an unverified publisher identity, so those are 1 each.
Outputs are Markdown trap files an agent can load plus a runnable scanner with concrete commands and likely/look semantics, earning 2 for usability. Marginal value over official docs lies in production failure modes and verification commands; the argument is persuasive but self-reported, earning 2. Cost-benefit is argued well (only eleven descriptions per turn, on-demand loading), earning 2.
The README claims every trap has a 'Verifying it' section, that mechanism claims were re-derived via disassembly and source review, that commands were executed verbatim, and points to evals/README.md for a comparison table — a traceable design. But only README and LICENSE were supplied, so trap files, evals, and scripts cannot be checked, giving claim_traceability 1. Cross-source corroboration rests on author self-report and external badges with no independent source, giving 1. The text does distinguish prose-only claims as marked, showing awareness of fact/inference separation, but execution cannot be verified from the evidence, giving 1.
- Only README and LICENSE were supplied; no trap files, CATALOG.md, evals/README.md, or scan.py are present, so README claims about 228 traps, eval results, and the verification pipeline cannot be checked in this static review.
- Installation relies on third-party channels (npx skills, /plugin marketplace) whose update and data-flow mechanics are not documented in-repo; review before deploying.
- The scanner's actual behavior (whether it only reads added lines, whether it touches the network) cannot be confirmed from the given evidence; audit it in isolation before wiring it into CI.
- Publisher identity is unverified by the FollowAgents registry; maintenance responsibility and update path rest on author self-description.
- GPL-3.0 is copyleft; assess compliance implications before merging skill files into proprietary projects or products.