Kotlin Multiplatform skill for Claude Code

# Shared module Gradle setup (Kotlin 2.4, AGP 9)

Read this when creating the shared module, migrating it to AGP 9, or setting up
XCFramework/SwiftPM distribution. Replace every `<check>` version with the current
release from the official changelog before committing; do not guess.

## gradle/libs.versions.toml

```toml
[versions]
kotlin = "2.4.0"
agp = "9.0.0"                 # needs Gradle 9.1+
coroutines = "<check>"
serialization = "<check>"
ktor = "<check>"              # 3.x
sqldelight = "2.4.0"
skie = "<check>"              # must list your Kotlin version as supported
turbine = "<check>"

[libraries]
coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }
serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "serialization" }
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-serialization-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }
ktor-client-mock = { module = "io.ktor:ktor-client-mock", version.ref = "ktor" }
sqldelight-android = { module = "app.cash.sqldelight:android-driver", version.ref = "sqldelight" }
sqldelight-native = { module = "app.cash.sqldelight:native-driver", version.ref = "sqldelight" }
sqldelight-coroutines = { module = "app.cash.sqldelight:coroutines-extensions", version.ref = "sqldelight" }
turbine = { module = "app.cash.turbine:turbine", version.ref = "turbine" }

[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
kotlinSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
androidApplication = { id = "com.android.application", version.ref = "agp" }
androidMultiplatformLibrary = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }
sqldelight = { id = "app.cash.sqldelight", version.ref = "sqldelight" }
skie = { id = "co.touchlab.skie", version.ref = "skie" }
```

Root `build.gradle.kts` declares each plugin with `apply false`.

## shared/build.gradle.kts

```kotlin
import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFramework

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidMultiplatformLibrary)
    alias(libs.plugins.kotlinSerialization)
    alias(libs.plugins.sqldelight)
    alias(libs.plugins.skie)            // optional; remove if using plain ObjC export
}

kotlin {
    android {                           // AGP 8.12+; replaces androidLibrary {}
        namespace = "com.example.shared"
        compileSdk = 36
        minSdk = 24
        withHostTest { }                // host (unit) tests are opt-in on this plugin
    }

    val xcf = XCFramework("Shared")
    listOf(iosArm64(), iosSimulatorArm64()).forEach { target ->
        target.binaries.framework {
            baseName = "Shared"
            isStatic = true
            xcf.add(this)
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation(libs.coroutines.core)
            implementation(libs.serialization.json)
            implementation(libs.ktor.client.core)
            implementation(libs.ktor.client.content.negotiation)
            implementation(libs.ktor.serialization.json)
            implementation(libs.sqldelight.coroutines)
        }
        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
            implementation(libs.sqldelight.android)
        }
        iosMain.dependencies {
            implementation(libs.ktor.client.darwin)
            implementation(libs.sqldelight.native)
        }
        commonTest.dependencies {
            implementation(kotlin("test"))
            implementation(libs.coroutines.test)
            implementation(libs.ktor.client.mock)
            implementation(libs.turbine)
        }
    }
}

sqldelight {
    databases {
        register("AppDatabase") {
            packageName.set("com.example.shared.db")
        }
    }
}
```

Notes:

- Under AGP 9 the old top-level `android { }` block and build variants do not exist for
  this module. `debugImplementation(...)` becomes `androidRuntimeClasspath(...)`.
- `android.enableLegacyVariantApi=true` in `gradle.properties` is a temporary escape
  hatch for plugins that still use the old variant API; AGP 10 removes it.
- If the module combines `com.android.application` with KMP, split it: an
  `androidApp` application module plus the `shared` library module.

## Driver factory (SQLDelight)

```kotlin
// commonMain
expect class DriverFactory { fun createDriver(): SqlDriver }
fun createDatabase(factory: DriverFactory): AppDatabase = AppDatabase(factory.createDriver())

// androidMain
actual class DriverFactory(private val context: Context) {
    actual fun createDriver(): SqlDriver = AndroidSqliteDriver(AppDatabase.Schema, context, "app.db")
}

// iosMain
actual class DriverFactory {
    actual fun createDriver(): SqlDriver = NativeSqliteDriver(AppDatabase.Schema, "app.db")
}
```

## Room KMP instead of SQLDelight

- Add KSP and the Room plugin, `room-runtime` and `androidx.sqlite:sqlite-bundled` in
  `commonMain`, and the Room compiler per target:
  `add("kspAndroid", ...)`, `add("kspIosArm64", ...)`, `add("kspIosSimulatorArm64", ...)`.
- Declare `@ConstructedBy(AppDatabaseConstructor::class)` on the database and an
  `expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase>`; Room
  generates the actuals.
- Build with `.setDriver(BundledSQLiteDriver())` so both platforms run the same SQLite.
- Check which artifact line the project uses (`androidx.room` stable vs `androidx.room3`
  alpha) before copying snippets.

## Swift-facing errors

```kotlin
class ApiException(message: String, cause: Throwable? = null) : Exception(message, cause)

class OrderService internal constructor(private val repo: OrderRepository) {
    @Throws(ApiException::class, kotlin.coroutines.cancellation.CancellationException::class)
    suspend fun placeOrder(cartId: String): OrderSummary = repo.place(cartId)
}
```

Include `CancellationException` in `@Throws` for suspend functions so Swift task
cancellation surfaces as an error instead of a crash.

## Direct integration (monorepo)

Xcode target -> Build Phases -> New Run Script Phase, placed before Compile Sources:

```sh
cd "$SRCROOT/.."
./gradlew :shared:embedAndSignAppleFrameworkForXcode
```

Build Settings: `ENABLE_USER_SCRIPT_SANDBOXING = NO`; add
`$(SRCROOT)/../shared/build/xcode-frameworks/$(CONFIGURATION)/$(SDK_NAME)` to Framework
Search Paths and `-framework Shared` to Other Linker Flags if the wizard did not.

For the Swift export experiment, replace the task with
`./gradlew :shared:embedSwiftExportForXcode` and add a `swiftExport { moduleName = "Shared" }`
block; keep the ObjC path on the main branch.

## SwiftPM distribution (separate iOS repo)

```bash
./gradlew :shared:assembleSharedReleaseXCFramework
cd shared/build/XCFrameworks/release
zip -r Shared.xcframework.zip Shared.xcframework
swift package compute-checksum Shared.xcframework.zip
```

```swift
// Package.swift in the distribution repo
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "Shared",
    platforms: [.iOS(.v15)],
    products: [.library(name: "Shared", targets: ["Shared"])],
    targets: [
        .binaryTarget(
            name: "Shared",
            url: "https://example.com/releases/1.4.0/Shared.xcframework.zip",
            checksum: "<output of compute-checksum>"
        )
    ]
)
```

Tag the distribution repo with the same version as the shared module. Automate in CI on
a macOS runner; never hand-edit checksums.

## Consuming Swift packages from Kotlin (Kotlin 2.4)

```kotlin
kotlin {
    swiftPMDependencies {
        swiftPackage(
            url = url("https://github.com/firebase/firebase-ios-sdk.git"),
            version = from("12.11.0"),
            products = listOf(product("FirebaseAnalytics")),
        )
    }
}
```

This replaces `cocoapods { pod(...) }` for calling iOS libraries from `iosMain`. Migrate
incrementally: add SwiftPM dependencies alongside the CocoaPods block, move call sites,
then remove CocoaPods last, following the official CocoaPods-to-SwiftPM migration guide.