From 68c198f2b276cc34ac6cec0e0c63d906242e2f65 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 15 Jul 2026 11:54:16 -0400 Subject: [PATCH] feat: add Kotlin Multiplatform (KMP) integration skill Adds a docs-only integration variant for the PostHog Kotlin Multiplatform SDK (posthog-kmp), mirroring the existing docs-only mobile entries (Flutter, Elixir, Go): - context/skills/integration/config.yaml: new `kmp` variant (docs-only, tags [kmp, kotlin, multiplatform, mobile], docs from /docs/libraries/kmp) - context/skills/integration/description-kmp-docs-only.md: KMP-specific docs-only description template - context/commandments.yaml: `kmp` framework guidelines (commonMain install, com.posthog.kmp package, PostHog.setup with per-platform PostHogContext, native-wrapper behavior, Maven Central versioning) Build generates `integration-kmp` skill (SKILL.md + fetched /docs/libraries/kmp reference + embedded commandments); `npm run build` and `npm test` (107) pass. This provides the KMP context the wizard fetches at runtime, unblocking PostHog/wizard#906. Co-Authored-By: Claude Opus 4.8 --- context/commandments.yaml | 9 ++++++ context/skills/integration/config.yaml | 8 ++++++ .../integration/description-kmp-docs-only.md | 28 +++++++++++++++++++ 3 files changed, 45 insertions(+) create mode 100644 context/skills/integration/description-kmp-docs-only.md diff --git a/context/commandments.yaml b/context/commandments.yaml index 971780d5..a04e20d0 100644 --- a/context/commandments.yaml +++ b/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 diff --git a/context/skills/integration/config.yaml b/context/skills/integration/config.yaml index 1dae71c4..c518d0d1 100644 --- a/context/skills/integration/config.yaml +++ b/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 diff --git a/context/skills/integration/description-kmp-docs-only.md b/context/skills/integration/description-kmp-docs-only.md new file mode 100644 index 00000000..260d837c --- /dev/null +++ b/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:")` 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}