ci(agents): add kmp-maps-build-guide porting and setup skill

Author: dkhawk

.agents/skills/kmp-maps-build-guide/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: kmp-maps-build-guide
+description: Comprehensive blueprint and expert guidance for porting libraries and sample sets to Kotlin Multiplatform (KMP) and Compose Multiplatform (CMP), covering build lifecycle, CocoaPods cinterop, Xcode build phase output tracking, and platform UI interoperability.
+---
+
+# KMP / CMP Porting & Build Blueprint
+
+This blueprint outlines the essential patterns, build lifecycle steps, and architecture rules for porting an existing Android library or sample catalog to **Kotlin Multiplatform (KMP)** and **Compose Multiplatform (CMP)**.
+
+---
+
+## 1. Porting Architecture & Source Set Organization
+
+When migrating an existing library or sample set to KMP:
+
+```mermaid
+graph TD
+    Common[commonMain<br/>Shared API & Composables] --> Android[androidMain<br/>AndroidView Interop]
+    Common --> iOS[iosMain / appleMain<br/>UIKit Interop / Cinterop]
+```
+
+### A. Source Set Hierarchy (`build.gradle.kts`)
+Ensure clear separation between pure state/composables and platform-specific view wrappers:
+- **`commonMain`**: Shared data models, public interface definitions (expect/actual), and platform-agnostic Compose UI.
+- **`androidMain`**: Android-specific implementations, Google Maps Android SDK wrappers, and `AndroidView` interop.
+- **`iosMain` / `appleMain`**: iOS-specific implementations, Cinterop bindings, and `UIKitView` / `UIKitViewController` wrappers.
+
+### B. Cinterop & Pod Linking (`cocoapods` Block)
+When wrapping native iOS SDKs (e.g., Google Maps), configure the CocoaPods plugin to generate Cinterop definitions:
+```kotlin
+kotlin {
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    cocoapods {
+        summary = "Shared KMP Library"
+        homepage = "https://github.com/..."
+        ios.deploymentTarget = "16.0" // Match underlying SDK requirements
+
+        // Link external iOS dependency
+        pod("GoogleMaps") {
+            version = "10.14.0"
+            extraOpts += listOf("-compiler-option", "-fmodules")
+        }
+    }
+}
+```
+
+---
+
+## 2. Platform UI Interoperability
+
+### A. Embedding Native iOS Views in Compose
+Use `UIKitView` or `UIKitViewController` to embed native iOS map/camera controllers inside shared Compose layouts:
+```kotlin
+@Composable
+actual fun PlatformMapView(modifier: Modifier) {
+    UIKitViewController(
+        factory = { MyNativeViewController() },
+        modifier = modifier
+    )
+}
+```
+
+### B. Exposing Compose to iOS Sample Apps
+Wrap root KMP composables in a `ComposeUIViewController` for seamless ingestion into native `UIViewController` or `UITableView` sample architectures:
+```kotlin
+fun MainViewController(): UIViewController = ComposeUIViewController {
+    MySharedSampleScreen()
+}
+```
+
+---
+
+## 3. iOS Build Lifecycle & Xcode Integration
+
+### A. Pre-Generate Dummy Framework
+Before running `pod install` in your sample iOS app, you must generate the initial Kotlin framework:
+```bash
+./gradlew :<kmp_module_name>:generateDummyFramework
+```
+*(Prevents CocoaPods from failing with `Kotlin framework doesn't exist yet`)*.
+
+### B. Script Phase Output Tracking (Xcode 16+)
+When adding custom **Run Script Build Phases** (e.g., dynamic secrets injection or code generation) to your Xcode targets:
+- **Rule**: Always declare the generated source output path (e.g., `$(SRCROOT)/iosApp/DeveloperSecrets.swift`) in the **Output Files** (`output_paths`) of that build phase.
+- **Why**: Modern Xcode build systems enforce strict input/output verification during dependency graph analysis and will fail with `Build input file cannot be found` if the output file is undeclared.
+
+### C. Pod Installation & Repo Sync
+Ensure your local podspec cache is updated when referencing new SDK versions:
+```bash
+pod install --repo-update
+```
+
+---
+
+## 4. Secrets & Credential Injection
+
+To keep sample repositories secure:
+1. Store API keys locally in an uncommitted `secrets.properties` file:
+   ```properties
+   MAPS_API_KEY=AIzaSy...
+   ```
+2. Inject keys via a Gradle task (for Android) or a pre-build Run Script (for iOS) that outputs a Git-ignored configuration struct (`DeveloperSecrets.swift`).
+
+---
+
+## 5. Verification Commands
+
+- **Verify Android Library & Sample App**:
+  ```bash
+  ./gradlew assembleDebug
+  ```
+- **Verify iOS XCFramework Compilation**:
+  ```bash
+  ./gradlew :<kmp_module_name>:podPublishDebugXCFramework
+  ```