Merge pull request #240 from PostHog/feat/kmp-support

feat: add Kotlin Multiplatform (KMP) integration skill

Author: turnipdabeets

context/commandments.yaml

@@ -278,3 +278,12 @@ commandments:
     - Call `PostHogAndroid.setup()` only once in the Application class's `onCreate()` method, so it's initialized as early as possible and only once.
     - Initialize PostHog in the Application class's `onCreate()` method
     - Ensure every activity has a `android:label` to accurately track screen views.
+
+  kmp:
+    - com.posthog:posthog-kmp is the Kotlin Multiplatform SDK package name; add it to the shared module's commonMain.dependencies in build.gradle.kts, not to androidMain, iosMain, or any platform-specific source set
+    - All PostHog APIs live in the com.posthog.kmp package — import com.posthog.kmp.PostHog, com.posthog.kmp.PostHogConfig, and com.posthog.kmp.PostHogContext
+    - Call PostHog.setup(config, context) exactly once, early in the app lifecycle, from shared code; do not also add posthog-android or posthog-js directly
+    - PostHogContext is platform-specific — on Android pass PostHogContext(application); on iOS and web use the no-argument PostHogContext()
+    - posthog-kmp is a thin wrapper that delegates to the native posthog-android, posthog-ios, and posthog-js SDKs, so session replay and autocapture availability follow the underlying native platform
+    - Use PostHogConfig.HOST_US or PostHogConfig.HOST_EU for the host, and read the project token from generated build config or environment values rather than hardcoding it
+    - The SDK is 0.x pre-release; check the latest posthog-kmp version on Maven Central (https://central.sonatype.com/artifact/com.posthog/posthog-kmp) before pinning instead of hardcoding a stale version

context/skills/integration/config.yaml

@@ -235,6 +235,14 @@ variants:
     tags: [flutter, dart, mobile]
     docs_urls:
       - https://posthog.com/docs/libraries/flutter.md
+
+  - id: kmp
+    template: description-kmp-docs-only.md
+    display_name: Kotlin Multiplatform
+    description: PostHog integration for Kotlin Multiplatform (KMP) shared code targeting Android, iOS, and web using the posthog-kmp SDK
+    tags: [kmp, kotlin, multiplatform, mobile]
+    docs_urls:
+      - https://posthog.com/docs/libraries/kmp.md
 
   - id: react-native
     example_paths: example-apps/react-native

context/skills/integration/description-kmp-docs-only.md

@@ -0,0 +1,28 @@
+# PostHog integration for {display_name}
+
+This skill helps you add PostHog analytics to {display_name} applications using the official PostHog Kotlin Multiplatform SDK documentation.
+
+## Instructions
+
+1. Detect the existing Kotlin Multiplatform app structure. Check `settings.gradle.kts`, the shared module's `build.gradle.kts` (look for the `kotlin("multiplatform")` plugin and a `commonMain` source set), and the per-platform entry points (Android `Application`/`Activity`, iOS `MainViewController`, web `main`).
+2. Read the reference files below before changing code. They are the source of truth for SDK installation, initialization, event capture, identification, feature flags, group analytics, session replay, and error tracking.
+3. Install the SDK by adding `implementation("com.posthog:posthog-kmp:<version>")` to the shared module's `commonMain` dependencies in `build.gradle.kts` — not to a platform-specific source set. Check the latest version on Maven Central (https://central.sonatype.com/artifact/com.posthog/posthog-kmp) rather than hardcoding a stale one.
+4. Initialize PostHog once, early in the app lifecycle, from shared code: `PostHog.setup(config = PostHogConfig(apiKey = ..., host = ...), context = PostHogContext())`. Use environment or generated build-config values for the project token and host. Never hardcode secrets.
+5. Build `PostHogContext` per platform: on Android pass `PostHogContext(application)`; on iOS and web use the no-argument `PostHogContext()`. All PostHog APIs live in the `com.posthog.kmp` package.
+6. Add `PostHog.identify(...)` at login/signup boundaries and `PostHog.reset()` on logout.
+7. Verify with the project's normal Gradle commands, such as `./gradlew build`, or the repository's existing checks.
+
+## Reference files
+
+{references}
+
+## Key principles
+
+- **Environment/configuration values**: Always use environment variables or generated build config for PostHog keys. Never hardcode them.
+- **Minimal changes**: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
+- **Match the docs**: Follow the Kotlin Multiplatform reference's initialization and capture patterns exactly.
+- **Analytics contract**: Treat event names, property names, and feature flag keys as part of an analytics contract. Reuse existing names and patterns found in the project. When introducing new ones, make them clear, descriptive, and consistent with existing conventions.
+
+## Framework guidelines
+
+{commandments}