KO

kotlin-multiplatform

Assists with KMP architectural decisions, including source set placement and managing cross-platform abstraction patterns.

Install

mkdir -p .claude/skills/kotlin-multiplatform && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2190" && unzip -o skill.zip -d .claude/skills/kotlin-multiplatform && rm skill.zip

Installs to .claude/skills/kotlin-multiplatform

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Platform abstraction decision-making for Amethyst KMP project. Guides when to abstract vs keep platform-specific,
source set placement (commonMain, jvmAndroid, platform-specific), expect/actual patterns. Covers primary targets
(Android, JVM/Desktop, iOS) with web/wasm future considerations. Integrates with gradle-expert for dependency issues.
Triggers on: abstraction decisions ("should I share this?"), source set placement questions, expect/actual creation,
build.gradle.kts work, incorrect placement detection, KMP dependency suggestions.
543 chars · catalog description✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Advanced

Key capabilities

  • →Advises on abstraction vs. duplication tradeoffs
  • →Determines appropriate source set placement
  • →Manages expect/actual pattern implementation
  • →Detects platform-specific code in common modules
  • →Suggests KMP dependency strategies

How it works

It applies a decision tree to evaluate if code should reside in `commonMain` or platform-specific sets based on platform API dependency and reuse frequency.

Inputs & outputs

You give it
Platform code issue or abstraction question
You get back
Decision recommendation and source set guidance

When to use kotlin-multiplatform

  • →Decide if code should be shared
  • →Determine source set placement
  • →Create expect/actual implementations
  • →Detect incorrect platform code placement

About this skill

Kotlin Multiplatform and Gradle in Amethyst

Module roles, the "share vs keep native" rule and the CLI-safe boundary are in AGENTS.md (Architecture, Feature Workflow). Package placement inside commons / commonsUI is in commons/ARCHITECTURE.md ("Where does my code go?", "Source sets") and commonsUI/ARCHITECTURE.md ("Platform slots"). Read those first; this skill adds the source-set mechanics and the build traps.

Modules

settings.gradle.kts includes 13: amethyst, nappletHost, benchmark, baselineprofile, geode, commons, commonsUI, nestsClient, marmotQuic, desktopApp, cli, relayBench, marmotBench. Quartz is the external libs.quartz (vitorpamplona/quartz) and QUIC the external libs.quic (vitorpamplona/quic-kmp); -PquartzDir=../quartz / -PquicKmpDir=../quic-kmp build a local checkout instead (an included build, so quic's own quartz dependency follows).

Source sets

Source setHoldsTargets
commonMainPure Kotlin. Compiled for iOS/native too, so no JVM APIsall
jvmAndroidJVM libraries shared by Android + Desktop: OkHttp, nestsClient, NWC/LNURLandroid, jvm
androidMain / jvmMainPlatform actuals (Keystore/DataStore vs keyring, Coil bridges)one each
iosMain, appleMain, nativeMain, linuxMain, macosMainquartz only (plus iosMain in commons/commonsUI)Apple / native
skikoMaincommonsUI code shared by Desktop and iOSjvm, ios

Targets: quartz builds android, jvm, iosArm64, iosSimulatorArm64, linuxX64, macosArm64. commons and commonsUI build android, jvm, iosArm64, iosSimulatorArm64. nestsClient, marmotQuic are android + jvm. There is no iosX64.

jvmAndroid is a custom intermediate set created with create("jvmAndroid") before androidMain/jvmMain depend on it (see commons/build.gradle.kts). Prefer the most common set that compiles: commonMain → jvmAndroid → platform.

kotlinx.serialization is the house JSON stack and OkHttp the house HTTP stack (AGENTS.md › Tech Stack). Nostr JSON (events, messages, filters, tags) goes through quartz's Kite (OptimizedJsonMapper, KiteWriter, KitePretty); quartz dropped Jackson in 2.4.0, so don't add Jackson back. Don't migrate JVM HTTP to Ktor. Jackson and OkHttp are banned in iOS-compiled sets, which the purity gate enforces.

expect/actual vs ports and slots

  • expect/actual for a small platform verb or value with no app state: KmpLock, ConcurrentSet, SecureKeyStorage, isDebug, formattedDateTime (commons), rememberTextSharer, rememberShortNotice (commonsUI). Put the actual in jvmAndroid when Android and Desktop share it.
  • A port (interface the shell implements) when the platform side needs app state or services: AccountViewModelHost, UserNoticeSink, LocalCacheHost.
  • A slot (CompositionLocal the front end installs) for things only a front end can draw: LocalNotePlatform, LocalRichTextPlatform.
  • Not every quartz singleton is expect: Secp256k1Instance, Log and LibSodiumInstance are plain objects in quartz/.../utils/.
  • Don't expect a whole screen or navigation; share it and put only the leaf behind a port or slot.

Purity gate: verifyKmpPurity

gradle/kmp-purity.gradle.kts, applied by commons and commonsUI (quartz keeps a copy) and wired into check, scans every iOS/native-compiled source set (commonMain, iosMain, skikoMain, …, and their tests) and fails on com.fasterxml.jackson, okhttp3, System.currentTimeMillis (use TimeUtils.now()), Thread.sleep, java.util.UUID (use kotlin.uuid.Uuid), kotlin.jvm.Synchronized or bare synchronized( (use KmpLock), kotlin.jvm.Volatile (use kotlin.concurrent.Volatile). CI runs it on Linux in the lint job; the macOS test-commons-ios / test-commonsui-ios jobs are authoritative. Run ./gradlew :commons:verifyKmpPurity :commonsUI:verifyKmpPurity after touching commonMain. Quartz has its own copy of the task and its own iOS CI.

Gradle traps

  • Versions live only in gradle/libs.versions.toml. Add the library there and reference libs.*; never hardcode a version or copy one into docs. Check the license first (AGENTS.md › Dependency Licensing).
  • test is an alias for each KMP module's jvmTest. Other targets (:commonsUI:testAndroidHostTest, the native ones) run only when named; see AGENTS.md › Build Commands.
  • testFixtures in KMP: the source-set dependencies { } block (KotlinDependencyHandler) has no testFixtures(...). Use a top-level block with the configuration name as a string: dependencies { "jvmAndroidTestImplementation"(testFixtures(project(":geode"))) }.
  • secp256k1 variants: secp256k1-kmp-common in commonMain, secp256k1-kmp-jni-android in androidMain, secp256k1-kmp-jni-jvm in jvmMain and JVM tests. All three share one version.ref. A JVM classpath with the android variant fails at load with UnsatisfiedLinkError.
  • R8: library keep rules ship in quartz/consumer-rules.pro. Never add a blanket -keep class com.vitorpamplona.quartz.** { *; }. R8 can't see reflection, so a moved/renamed reflective class is a silent release break: before tagging, run python3 tools/r8-verify/verify_reflection_contract.py amethyst/build/outputs/mapping/<variant>/ (the release workflow checks playRelease and fdroidRelease) and update tools/r8-verify/reflection-contract.txt when you move a listed class.

Extracting Android code to shared modules

Steps and the Android → multiplatform replacement table: references/extract-composable.md.

When not to use it

  • →Pure Android-only application development
  • →Projects not intended for multiplatform sharing
  • →Cases where abstraction costs exceed duplication benefits

Limitations

  • →Abstraction recommendations are subjective to project goals
  • →Requires knowledge of the specific target platforms
  • →Complex UI logic remains difficult to abstract

How it compares

It provides architectural guidance specific to the KMP ecosystem rather than general coding advice.

Compared to similar skills

kotlin-multiplatform side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
kotlin-multiplatform (this skill)326moReviewAdvanced
android-clean-architecture04moNo flagsIntermediate
android-kotlin-development2688moReviewAdvanced
backend-microservice-development26moNo flagsIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

More by vitorpamplona

View all by vitorpamplona →

compose-expert

vitorpamplona

Advanced Compose Multiplatform UI patterns for shared composables. Use when working with visual UI components, state management patterns (remember, derivedStateOf, produceState), recomposition optimization (@Stable/@Immutable visual usage), Material3 theming, custom ImageVector icons, or determining whether to share UI in commonMain vs keep platform-specific. Delegates navigation to android-expert/desktop-expert. Complements kotlin-expert (handles Kotlin language aspects of state/annotations).

632

kotlin-expert

vitorpamplona

Advanced Kotlin patterns for AmethystMultiplatform. Flow state management (StateFlow/SharedFlow), sealed hierarchies (classes vs interfaces), immutability (@Immutable, data classes), DSL builders (type-safe fluent APIs), inline functions (reified generics, performance). Use when working with: (1) State management patterns (StateFlow/SharedFlow/MutableStateFlow), (2) Sealed classes or sealed interfaces, (3) @Immutable annotations for Compose, (4) DSL builders with lambda receivers, (5) inline/reified functions, (6) Kotlin performance optimization. Complements kotlin-coroutines agent (async patterns) - this skill focuses on Amethyst-specific Kotlin idioms.

526

kotlin-coroutines

vitorpamplona

Advanced Kotlin coroutines patterns for AmethystMultiplatform. Use when working with: (1) Structured concurrency (supervisorScope, coroutineScope), (2) Advanced Flow operators (flatMapLatest, combine, merge, shareIn, stateIn), (3) Channels and callbackFlow, (4) Dispatcher management and context switching, (5) Exception handling (CoroutineExceptionHandler, SupervisorJob), (6) Testing async code (runTest, Turbine), (7) Nostr relay connection pools and subscriptions, (8) Backpressure handling in event streams. Delegates to kotlin-expert for basic StateFlow/SharedFlow patterns. Complements nostr-expert for relay communication.

311

nostr-expert

vitorpamplona

Nostr protocol implementation patterns in Quartz (AmethystMultiplatform's KMP Nostr library). Use when working with: (1) Nostr events (creating, parsing, signing), (2) Event kinds and tags, (3) NIP implementations (57 NIPs in quartz/), (4) Event builders and TagArrayBuilder DSL, (5) Nostr cryptography (secp256k1, NIP-44 encryption), (6) Relay communication patterns, (7) Bech32 encoding (npub, nsec, note, nevent). Complements nostr-protocol agent (NIP specs) - this skill provides Quartz codebase patterns and implementation details.

323

gradle-expert

vitorpamplona

Build optimization, dependency resolution, and multi-module KMP troubleshooting for AmethystMultiplatform. Use when working with: (1) Gradle build files (build.gradle.kts, settings.gradle), (2) Version catalog (libs.versions.toml), (3) Build errors and dependency conflicts, (4) Module dependencies and source sets, (5) Desktop packaging (DMG/MSI/DEB), (6) Build performance optimization, (7) Proguard/R8 configuration, (8) Common KMP + Android Gradle issues (Compose conflicts, secp256k1 JNI variants, source set problems).

19

Search skills

Search the agent skills registry