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.zipInstalls 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.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
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 set | Holds | Targets |
|---|---|---|
commonMain | Pure Kotlin. Compiled for iOS/native too, so no JVM APIs | all |
jvmAndroid | JVM libraries shared by Android + Desktop: OkHttp, nestsClient, NWC/LNURL | android, jvm |
androidMain / jvmMain | Platform actuals (Keystore/DataStore vs keyring, Coil bridges) | one each |
iosMain, appleMain, nativeMain, linuxMain, macosMain | quartz only (plus iosMain in commons/commonsUI) | Apple / native |
skikoMain | commonsUI code shared by Desktop and iOS | jvm, 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 injvmAndroidwhen 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,LogandLibSodiumInstanceare plainobjects inquartz/.../utils/. - Don't
expecta 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 referencelibs.*; never hardcode a version or copy one into docs. Check the license first (AGENTS.md› Dependency Licensing). testis an alias for each KMP module'sjvmTest. Other targets (:commonsUI:testAndroidHostTest, the native ones) run only when named; seeAGENTS.md› Build Commands.- testFixtures in KMP: the source-set
dependencies { }block (KotlinDependencyHandler) has notestFixtures(...). Use a top-level block with the configuration name as a string:dependencies { "jvmAndroidTestImplementation"(testFixtures(project(":geode"))) }. - secp256k1 variants:
secp256k1-kmp-commonincommonMain,secp256k1-kmp-jni-androidinandroidMain,secp256k1-kmp-jni-jvminjvmMainand JVM tests. All three share oneversion.ref. A JVM classpath with the android variant fails at load withUnsatisfiedLinkError. - 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, runpython3 tools/r8-verify/verify_reflection_contract.py amethyst/build/outputs/mapping/<variant>/(the release workflow checksplayReleaseandfdroidRelease) and updatetools/r8-verify/reflection-contract.txtwhen 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.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| kotlin-multiplatform (this skill) | 32 | 6mo | Review | Advanced |
| android-clean-architecture | 0 | 4mo | No flags | Intermediate |
| android-kotlin-development | 268 | 8mo | Review | Advanced |
| backend-microservice-development | 2 | 6mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by vitorpamplona
View all by vitorpamplona →You might also like
android-clean-architecture
farhankabir133
Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns.
android-kotlin-development
aj-geddes
Develop native Android apps with Kotlin. Covers MVVM with Jetpack, Compose for modern UI, Retrofit for API calls, Room for local storage, and navigation architecture.
backend-microservice-development
TencentBlueKing
后端微服务开发规范,涵盖目录结构、分层架构(API/Service/DAO)、依赖注入、配置管理、Spring Boot 最佳实践。当用户进行后端开发、创建新微服务、编写 Kotlin/Java 代码或设计服务架构时使用。
kmp-cmp-app-builder
firdaus1453
>
android-architecture
huyhunhngc
>
mobile-architect-agent
srednoff888-art
Agent profile for coordinate mobile app architecture across iOS, Android, Expo/React Native, offline states, permissions, and releases. Use when Codex needs a specialist agent perspective for planning, implementation, review, debugging, validation, or handoff in this domain.