swift-kmp-skill

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                                                    ┃
┃   ◆  swift · kmp                  AI Coding Skill  ┃
┃   ────────────────────────────────────────────     ┃
┃                                                    ┃
┃   KMP  ──────────────────────────────────► Swift   ┃
┃                                                    ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

What This Skill Covers

🔗 Embedding Compose views in SwiftUI? See the companion swiftui-compose skill.

Core Principle

Feature modules know nothing about KMP.
They receive @Sendable closures with pure Swift types.
Every KMP import lives in one place — the bridge layer.

KMP iOS Framework  (direct integration / SwiftPM)
       │  @preconcurrency import — bridge layer only
       ▼
  Bridge Layer
  ┌─ Interactors (request/response KMP calls)
  ├─ Services (long-lived stream/lifecycle bridge)
  └─ Mappers (kill invalid state here)
       │  @Sendable closures with pure Swift types only
       ▼
  Feature Modules (SPM packages)
  (no KMP imports — no Kotlin types — no KotlinThrowable)

Benefits: fast builds, KMP changes don't cascade into feature code, KMP is replaceable,
invalid states are killed in mappers before features ever see data.

Files

Token budget: SKILL.md (~1.7k tokens) covers most tasks. Load one reference only when
you need the detailed API contract for that topic.

🔗 Embedding Compose views in SwiftUI? See the companion swiftui-compose skill — it covers UIViewControllerRepresentable wiring, the coordinator pattern, bidirectional state, and teardown.

Quick Start

Install

# 1. Clone into the canonical skill location:
git clone https://github.com/sorunokoe/swift-kmp-skill.git \
  /path/to/your-project/.github/skills/swift-kmp

# 2. (Optional) Remove git history — you own this copy:
rm -rf /path/to/your-project/.github/skills/swift-kmp/.git

Why .github/skills/swift-kmp/? This is the path GitHub Copilot, Cursor, and the
skills-evolution governance toolkit
all discover skills from.

GitHub Copilot

In Copilot Chat, after installing:

@swift-kmp Implement a ProfileInteractor that fetches user data from KMP

Claude / Any AI agent

Load .github/skills/swift-kmp/SKILL.md, then
.github/skills/swift-kmp/references/interactor-pattern.md.

Implement a Swift interactor that:
- Calls component.profileInteractor.fetchProfile() (Kotlin suspend function)
- Maps the KMP result to a Swift ProfileData struct
- Catches KotlinThrowable and returns Result<ProfileData, ProfileError>

Key Rules (summary)

• ❌ No KMP framework import in feature modules — only the bridge/main target
• ❌ No KotlinThrowable in feature code — catch and re-throw as typed Swift Error
• ❌ No SkieSwiftFlow<T> in feature modules — wrap to AsyncStream at the boundary
• ❌ No raw Kotlin collections (KotlinList<T>) in feature modules — map to [T]
• ✅ @concurrent nonisolated on interactor bridge methods
• ✅ continuation.onTermination always set when wrapping Kotlin flows

Full rules and review checklist in SKILL.md.

Official Documentation

Requirements

Related Skills

🔗 Embedding Compose Multiplatform views inside your SwiftUI app?
Check out swiftui-compose — the companion skill covering UIViewControllerRepresentable wiring, the coordinator pattern, bidirectional state sharing, and dismantleUIViewController teardown.

Automated Maintenance

This skill is governed by skills-evolution — AI skill governance that keeps guidance files accurate and up to date automatically.

gh-aw (recommended)

# PR review — AI feedback on every PR touching SKILL.md or references/**
gh aw add sorunokoe/skills-evolution/workflows/oss-skill-pr-check.md@latest

# Monthly update — version checks, AI content patches, opens PR
gh aw add sorunokoe/skills-evolution/workflows/oss-skill-update.md@latest

gh aw compile

GitHub Actions

# .github/workflows/skill-health.yml
name: Skill Health
on:
  schedule:
    - cron: "0 3 1 * *"
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
  models: read
jobs:
  health:
    uses: sorunokoe/skills-evolution/.github/workflows/oss-skill-health.yml@latest
    with:
      enable_ai_skill_update: true
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

Contributing

See CONTRIBUTING.md for how to improve patterns or add new reference files.

License

MIT