feat: add /skills

README.md

@@ -37,13 +37,68 @@ Checkout Kit is a monorepo containing all the platforms Checkout Kit supports to
 | [`com.shopify:checkout-kit`](platforms/android/)                       | [![Maven Central](https://img.shields.io/maven-central/v/com.shopify/checkout-kit.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/com.shopify/checkout-kit)                                                                                              | Maven Central                    | Android checkout presentation and accelerated checkout support. | [Readme](platforms/android/README.md)      |
 | [`@shopify/checkout-kit`](platforms/react-native/)                     | [![npm latest](https://img.shields.io/npm/v/@shopify/checkout-kit/latest.svg?label=npm)](https://www.npmjs.com/package/@shopify/checkout-kit)                                                                                                                              | npm                              | React Native wrapper for Checkout Kit.                          | [Readme](platforms/react-native/README.md) |
 
+## AI Quick Start
+
+### Install Checkout Skills
+
+Install the Checkout Kit skills:
+
+```bash
+npx skills add Shopify/checkout-kit
+```
+
+Checkout Kit skills:
+
+| Skill                                                                                                           | Use when                                                                                            |
+| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| [Migrate from Checkout Sheet Kit to Checkout Kit](skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md) | Moving from legacy package names to Checkout Kit v1, including version reset and lifecycle changes. |
+| [Present, preload, and invalidate checkout](skills/checkout-kit-present-preload-invalidate/SKILL.md)            | Applying shared checkout lifecycle guidance across platforms.                                       |
+| [Lifecycle events](skills/checkout-kit-lifecycle-events/SKILL.md)                                               | Handling completion, cancellation, failure, external links, and protocol notifications.             |
+
+### Local Clone
+
+Checkout Kit works best with AI tools when they can inspect this repository locally instead of relying only on web search.
+
+1. Clone a shallow local copy of Checkout Kit:
+
+   ```bash
+   git clone --depth 1 https://github.com/Shopify/checkout-kit.git ~/.local/share/checkout-kit/checkout-kit
+   ```
+
+2. Add a reference to your app's agent instructions file. Replace `~/some-repo/CLAUDE.md` with your app's `CLAUDE.md`, `AGENTS.md`, or equivalent file:
+
+   ```bash
+   cat >> ~/some-repo/CLAUDE.md <<'EOF'
+   ## Local Checkout Kit Source
+
+   The Checkout Kit repository is cloned to
+   `~/.local/share/checkout-kit/checkout-kit` for reference. Use this local
+   source to explore APIs, find usage examples, inspect protocol schemas, and
+   understand implementation details when the documentation is not enough.
+
+   Prefer local source over memory. Use Shopify docs only to confirm current
+   public guidance: https://shopify.dev/docs/storefronts/mobile
+   EOF
+   ```
+
+3. Ask your AI assistant to read the relevant skill before suggesting code:
+
+   ```text
+   Launch a Checkout Kit research agent to understand the library on the `.local/share/checkout-kit/checkout-kit` clone.
+   Read README.md, relevant library source code (swift/, /android, /react-native),
+   protocol/schemas/, the relevant skill, and the skill's references/guide.md before suggesting code.
+   ```
+
 ## Versioning
 
-Checkout Kit is the new name for the Checkout Sheet Kit SDKs. It resets the version line to Checkout Kit v1, and all future development will be under Checkout Kit.
+Checkout Kit is the new name for the Checkout Sheet Kit SDKs. It is a renamed and reset release line: all future development moves to the new Checkout Kit package names, with `Sheet` removed from the package name, and all three platforms start again at Checkout Kit `v1`.
+
+### Legacy Checkout Sheet Kit
 
-### Legacy v3
+The legacy Checkout Sheet Kit lines are deprecated and remain available for apps maintaining older integrations. Checkout Sheet Kit for Swift and Checkout Sheet Kit for Android end on their `v3` major-version lines. Checkout Sheet Kit for React Native ends on its `v4` New Architecture release line. These versions do not roll forward into Checkout Kit; Checkout Kit starts at `v1` for Swift, Android, and React Native.
 
-The legacy Checkout Sheet Kit lines are deprecated and remain available for apps maintaining older integrations.
+> [!TIP]
+> Use the [Migrate from Checkout Sheet Kit to Checkout Kit](skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md) skill when upgrading.
 
 | Platform     | Status                                                                  | Package                             | Final release | Readme                                                                      |
 | ------------ | ----------------------------------------------------------------------- | ----------------------------------- | ------------- | --------------------------------------------------------------------------- |

skills/checkout-kit-lifecycle-events/AGENTS.md

@@ -0,0 +1,3 @@
+# Checkout Kit Lifecycle Events
+
+Use `SKILL.md` as the entrypoint for this skill. Read `references/guide.md` for shared lifecycle event guidance, then read the target platform file: `references/swift.md`, `references/android.md`, or `references/react-native.md`.

skills/checkout-kit-lifecycle-events/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: checkout-kit-lifecycle-events
+description: Use when implementing, migrating, or reviewing Checkout Kit lifecycle event handling, including completion, cancellation, failure, external links, and UCP-backed Checkout Protocol notifications.
+---
+
+# Checkout Kit Lifecycle Events
+
+Use this skill when the user needs to handle checkout lifecycle events, migrate callback/event-processor code, or wire protocol notifications into app state.
+
+## Start with local truth
+
+Read these local files before suggesting code:
+
+- `README.md` for current package and docs links.
+- The target platform README: `swift/README.md`, `android/README.md`, or `react-native/README.md`.
+- `protocol/services/shopping/embedded.openrpc.json` for protocol notifications and request methods.
+- `protocol/schemas/` for UCP payload shape.
+- `references/guide.md` for shared lifecycle event guidance.
+- The platform sample for the target app: `references/swift.md`, `references/android.md`, or `references/react-native.md`.
+
+Prefer local source over memory. Use Shopify docs only to confirm current public guidance: https://shopify.dev/docs/storefronts/mobile

skills/checkout-kit-lifecycle-events/references/android.md

@@ -0,0 +1,48 @@
+# Android
+
+```kotlin
+import com.shopify.checkoutkit.CheckoutProtocol
+import com.shopify.checkoutkit.DefaultCheckoutEventProcessor
+import com.shopify.checkoutkit.ShopifyCheckoutKit
+import com.shopify.checkoutkit.lifecycleevents.CheckoutCompletedEvent
+
+val protocolClient = CheckoutProtocol.Client()
+    .on(CheckoutProtocol.ready) { payload ->
+        recordDelegations(payload.delegations)
+    }
+    .on(CheckoutProtocol.start) { checkout ->
+        hideLoadingShell(checkout)
+    }
+    .on(CheckoutProtocol.complete) { checkout ->
+        navigateToConfirmation(checkout)
+    }
+    .on(CheckoutProtocol.messagesChange) { checkout ->
+        renderCheckoutMessages(checkout.messages)
+    }
+    .on(CheckoutProtocol.lineItemsChange) { checkout ->
+        syncCartSummary(checkout.lineItems)
+    }
+    .on(CheckoutProtocol.buyerChange) { checkout ->
+        syncBuyerState(checkout.buyer)
+    }
+    .on(CheckoutProtocol.paymentChange) { checkout ->
+        syncPaymentState(checkout.payment)
+    }
+    .onOpenExternalUrl { uri ->
+        openExternalUrl(uri)
+        true
+    }
+
+val processor = object : DefaultCheckoutEventProcessor(activity) {
+    override fun onCheckoutCompleted(event: CheckoutCompletedEvent) {
+        // Keep only if the app still needs legacy completion handling.
+    }
+}
+
+ShopifyCheckoutKit.present(
+    checkoutUrl = checkoutUrl,
+    context = activity,
+    checkoutEventProcessor = processor,
+    communicationClient = protocolClient,
+)
+```

skills/checkout-kit-lifecycle-events/references/guide.md

@@ -0,0 +1,39 @@
+# Lifecycle Events Guide
+
+## Core Model
+
+Lifecycle handling should connect checkout state changes to app-owned side effects: navigation, confirmation screens, loading UI, cart refreshes, external URL handling, and error UI.
+
+Prefer protocol notifications where the platform exposes them. Keep legacy callbacks only when the platform still requires them or when the protocol does not expose the event needed by the app.
+
+## Protocol Events
+
+Use protocol events as the source of truth when available:
+
+- `ec.ready`: handshake and delegated capability discovery.
+- `ec.start`: checkout is visible and interactive enough for host UI transitions.
+- `ec.complete`: checkout completed; navigate or refresh order state.
+- `ec.messages.change`: checkout warnings, errors, and informational messages changed.
+- `ec.line_items.change`: line items changed.
+- `ec.buyer.change`: buyer details changed.
+- `ec.payment.change`: payment state changed.
+- `ec.window.open_request`: checkout requests that the host open an external URL.
+
+Do not assume every legacy callback has a one-to-one replacement. If a callback mixed several concerns, split it into protocol handlers and app-owned state transitions.
+
+## Platform Samples
+
+Read the platform file for the target app:
+
+- `references/swift.md`
+- `references/android.md`
+- `references/react-native.md`
+
+## Review Checklist
+
+- Completion handling navigates or refreshes state exactly once.
+- Cancellation and failure paths restore the host UI and preserve cart state.
+- External links are handled intentionally.
+- Protocol handlers update app state without duplicating legacy callback side effects.
+- Web pixel events are not relayed to the native layer.
+- Event payload handling does not assume personally identifiable information is present.

skills/checkout-kit-lifecycle-events/references/react-native.md

@@ -0,0 +1,44 @@
+# React Native
+
+Use this as the intended wrapper shape. Check the installed React Native package before copying names directly.
+
+```tsx
+import {Linking} from 'react-native';
+import {
+  createCheckoutProtocolClient,
+  useShopifyCheckoutSheet,
+} from '@shopify/checkout-kit';
+
+const shopifyCheckout = useShopifyCheckoutSheet();
+
+const checkoutClient = createCheckoutProtocolClient()
+  .on('ec.ready', ({delegate}) => {
+    recordDelegations(delegate);
+  })
+  .on('ec.start', ({checkout}) => {
+    hideLoadingShell(checkout);
+  })
+  .on('ec.complete', ({checkout}) => {
+    navigateToConfirmation(checkout);
+  })
+  .on('ec.messages.change', ({checkout}) => {
+    renderCheckoutMessages(checkout.messages);
+  })
+  .on('ec.line_items.change', ({checkout}) => {
+    syncCartSummary(checkout.line_items);
+  })
+  .on('ec.buyer.change', ({checkout}) => {
+    syncBuyerState(checkout.buyer);
+  })
+  .on('ec.payment.change', ({checkout}) => {
+    syncPaymentState(checkout.payment);
+  })
+  .onOpenExternalUrl((url) => {
+    Linking.openURL(url);
+    return true;
+  });
+
+shopifyCheckout.present(checkoutUrl, {
+  protocolClient: checkoutClient,
+});
+```

skills/checkout-kit-lifecycle-events/references/swift.md

@@ -0,0 +1,46 @@
+# Swift
+
+```swift
+import ShopifyCheckoutKit
+import UIKit
+
+let checkout = ShopifyCheckoutKit.present(checkout: checkoutURL, from: viewController)
+    .onComplete { event in
+        navigateToConfirmation(event)
+    }
+    .onCancel {
+        handleCheckoutCancel()
+    }
+    .onFail { error in
+        renderCheckoutError(error)
+    }
+    .onLinkClick { url in
+        openExternalURL(url)
+    }
+```
+
+```swift
+final class AppCheckoutDelegate: CheckoutDelegate {
+    func checkoutDidComplete(event: CheckoutCompletedEvent) {
+        navigateToConfirmation(event)
+    }
+
+    func checkoutDidCancel() {
+        handleCheckoutCancel()
+    }
+
+    func checkoutDidFail(error: CheckoutError) {
+        renderCheckoutError(error)
+    }
+
+    func checkoutDidClickLink(url: URL) {
+        openExternalURL(url)
+    }
+}
+
+ShopifyCheckoutKit.present(
+    checkout: checkoutURL,
+    from: viewController,
+    delegate: AppCheckoutDelegate()
+)
+```

skills/checkout-kit-present-preload-invalidate/AGENTS.md

@@ -0,0 +1,3 @@
+# Present, Preload, and Invalidate Checkout
+
+Use `SKILL.md` as the entrypoint for this skill. Read `references/guide.md` for shared lifecycle rules, then read the target platform file: `references/swift.md`, `references/android.md`, or `references/react-native.md`.

skills/checkout-kit-present-preload-invalidate/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: checkout-kit-present-preload-invalidate
+description: Use when implementing or reviewing Checkout Kit present, preload, and invalidate behavior across platforms, especially when deciding when to preload after cart changes and when to clear cached checkout state.
+---
+
+# Present, Preload, and Invalidate Checkout
+
+Use this skill when the user is wiring Checkout Kit into a cart or checkout flow, improving checkout performance, or debugging stale checkout state.
+
+## Start with local truth
+
+Read these local files before suggesting code:
+
+- `README.md` for current package and docs links.
+- The target platform README: `swift/README.md`, `android/README.md`, or `react-native/README.md`.
+- Sample apps for realistic cart and checkout wiring.
+- The platform source for exact function names and configuration shape.
+- `references/guide.md` for lifecycle rules, platform-neutral flow, and review checklist.
+- The platform sample for the target app: `references/swift.md`, `references/android.md`, or `references/react-native.md`.
+
+Prefer local source over memory. Use Shopify docs only to confirm current public guidance: https://shopify.dev/docs/storefronts/mobile

skills/checkout-kit-present-preload-invalidate/references/android.md

@@ -0,0 +1,45 @@
+# Android
+
+```kotlin
+import androidx.lifecycle.lifecycleScope
+import com.shopify.checkoutkit.ShopifyCheckoutKit
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+
+private var preloadJob: Job? = null
+private var preloadedCheckoutUrl: String? = null
+
+fun onCartStateSettled(checkoutUrl: String) {
+    preloadJob?.cancel()
+    preloadJob = lifecycleScope.launch {
+        delay(300)
+        ShopifyCheckoutKit.preload(checkoutUrl, activity)
+        preloadedCheckoutUrl = checkoutUrl
+    }
+}
+
+fun onCheckoutTapped(checkoutUrl: String) {
+    ShopifyCheckoutKit.present(
+        checkoutUrl = checkoutUrl,
+        context = activity,
+        checkoutEventProcessor = checkoutEventProcessor,
+    )
+}
+
+fun onCheckoutAffectingStateChanged(freshCheckoutUrl: String, cartOrBuyerChanged: Boolean) {
+    val preloadedCheckoutIsStale = preloadedCheckoutUrl != null && preloadedCheckoutUrl != freshCheckoutUrl
+
+    if (cartOrBuyerChanged && preloadedCheckoutIsStale) {
+        ShopifyCheckoutKit.invalidate()
+        preloadedCheckoutUrl = null
+    }
+
+    onCartStateSettled(freshCheckoutUrl)
+}
+
+fun onSessionBoundaryChanged() {
+    ShopifyCheckoutKit.invalidate()
+    preloadedCheckoutUrl = null
+}
+```