clerk-swift

Clerk Swift (Native iOS and macOS)

This skill builds Clerk authentication UI in native Swift projects: prebuilt ClerkKitUI views or custom flows on ClerkKit. Setup (SDK, capabilities, native registration, and Clerk initialization) comes first and has its own workflow.

Activation Rules

Activate this skill when either condition is true:

• The user explicitly asks for Swift, SwiftUI, UIKit, or native iOS or macOS Clerk implementation.
• The project appears to be native Swift (for example .xcodeproj, .xcworkspace, Package.swift, Swift targets).

Do not activate this skill when either condition is true:

• The project is Expo.
• The project is React Native.

If Expo/React Native signals are present, route to the general setup skill instead of this one.

Set up Clerk first

If Clerk isn't set up yet (no clerk-ios package, no Clerk.configure call, or no Clerk application chosen), follow the iOS setup prompt before any UI work. It uses the Clerk CLI to choose a Clerk application, install the SDK, configure capabilities, register the native app, and hand off the remaining Swift integration. The CLI also supplies the publishable key, so don't ask the user to paste one.

If the CLI can't set up the project (for example, Xcode isn't available or the project isn't supported), follow the manual iOS quickstart instead.

If the user already asked for sign-in UI, such as a custom flow, continue here once setup's build check passes. Otherwise, return to this skill when the user wants sign-in UI added or changed.

What Do You Need?

Quick Start

Decision Tree

User asks for Clerk in Swift
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Clerk set up in this project?
    |     |
    |     +-- NO -> Follow the iOS setup prompt (manual quickstart if the CLI can't)
    |     |
    |     +-- YES -> Continue
    |
    +-- Existing auth UI detected?
    |     |
    |     +-- Prebuilt views detected -> Load references/prebuilt.md
    |     |
    |     +-- Custom flow detected -> Load references/custom.md
    |     |
    |     +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
    |
    +-- Make targeted prerequisite changes for the selected flow
    |
    +-- Implement using selected flow reference

Flow References

After flow type is known, load exactly one:

• Prebuilt flow: references/prebuilt.md
• Custom flow: references/custom.md

Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.

Interaction Contract

Before UI implementation edits, the agent must have a flow choice: prebuilt or custom. If it's missing, ask the user and wait for the answer. Only skip asking when the user has already chosen in this conversation or the existing UI makes the choice clear.

Preserve Completed Setup

• Keep the existing Clerk.configure call and how the app loads its publishable key, including plist, build-setting, or other custom key loading. Don't replace it with a hardcoded key.
• Keep existing package requirements, capabilities, and entitlements. Add only what the selected flow needs and is missing.
• To check Clerk and project setup without changing anything, run npx -y clerk@latest doctor. It reports SDK linkage, capabilities, native registration, and the Apple connection.

Source-Driven Implementation

Use the installed clerk-ios package source as the reference for UI behavior, especially for custom flows.

Workflow

1. Detect native Swift vs Expo/React Native.
2. If Clerk isn't set up, follow the iOS setup prompt (or the manual quickstart when the CLI can't set up the project), then continue.
3. If the flow type isn't known, ask for prebuilt or custom.
4. Load the matching flow reference.
5. Check that flow's prerequisites and make only the missing, targeted changes, preserving completed setup and custom key loading.
6. Implement using the selected reference.
7. Verify using the selected reference, then build the target.

Common Pitfalls

See Also

• iOS setup prompt for setting up Clerk with the Clerk CLI
• clerk skill for top-level Clerk routing
• clerk-setup skill for non-native or cross-framework setup
• https://github.com/clerk/clerk-ios