Clerk Swift

Clerk Swift (Native iOS)

This skill implements Clerk in native Swift/iOS projects by reading installed package source and mirroring current ClerkKit/ClerkKitUI behavior.

Activation Rules

Activate this skill when either condition is true:

• The user explicitly asks for Swift, SwiftUI, UIKit, or native iOS Clerk implementation.
• The project appears to be native iOS/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.

What Do You Need?

Quick Start

Decision Tree

User asks for Clerk in Swift/iOS
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> 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
    |
    +-- Ensure publishable key and direct wiring
    |
    +-- Ensure clerk-ios is installed
    |
    +-- Inspect ClerkKitUI Environment field usage
    |
    +-- Call /v1/environment using that field map
    |
    +-- Visit/read quickstart URL from installed clerk-ios package README
    |
    +-- Verify all quickstart prerequisites are completed
    |
    +-- 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 any implementation edits, the agent must have both:

• flow choice: prebuilt or custom
• a real Clerk publishable key

If either value is missing from the user request/context:

• ask the user for the missing value(s)
• pause and wait for the answer
• do not edit files or install dependencies yet

Only skip asking when the user has already explicitly provided the value in this conversation.

Source-Driven Templates

Do not hardcode implementation examples in this skill. Inspect current installed package source before implementing.

Execution Gates (Do Not Skip)

1. No implementation edits before prerequisites

• Do not edit project files until flow type is confirmed and a valid publishable key is available.

2. Missing flow or key must trigger a question

• If flow choice is missing, explicitly ask: prebuilt views or custom flow.
• If publishable key is missing/placeholder/invalid, explicitly ask for a real key.
• Do not continue until both answers are provided.

3. Publishable key wiring mode is mandatory

• Use the developer-provided publishable key plainly in app configuration passed to Clerk.configure.
• Do not introduce plist/local-secrets/env-file/build-setting indirection unless explicitly requested.

4. Package install/version policy is mandatory

• If clerk-ios is not installed, add it using the latest available release with an up-to-next-major requirement.
• Do not pin an exact package version unless the developer explicitly asks for exact pinning.

5. ClerkKitUI Environment field inspection is mandatory

• After package install, inspect installed ClerkKitUI source and identify which Environment fields gate auth behavior for the selected flow.
• Build an agent-internal field map before any /v1/environment call.

6. Environment call is mandatory (both flows)

• Make a direct HTTP call to /v1/environment only after package install and step 5 field-map inspection.
• Pass the response into the selected reference workflow using the ClerkKitUI-aligned field map:
  • prebuilt: use it to determine whether Apple is enabled and capability changes are needed
  • custom: perform full normalization/matrix handling as agent-internal analysis only (never persist matrix artifacts in project code)

7. Reference-file discipline is mandatory

• Once flow is selected, follow only that flow reference file for implementation and verification.

8. Quickstart compliance is mandatory

• Find the iOS quickstart URL in the installed clerk-ios package README, append .md, then visit and read that markdown URL.
• Audit the project against all quickstart setup steps before finishing.
• If required quickstart setup is missing, implement it before completing the task.
• This includes adding any missing Associated Domains entries and any other required app capabilities from the quickstart.
• Explicitly execute the quickstart step Add associated domain capability (https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability) and ensure the associated-domain entry matches quickstart requirements (webcredentials:{YOUR_FRONTEND_API_URL}).

9. Custom-flow AuthView structure parity is mandatory

• For custom flow, layout and flow structure must remain materially close to ClerkKitUI AuthView defaults.
• If the developer did not explicitly request a different UX, do not introduce major structural/layout deviations from AuthView.
• If unsure/confused about custom sequencing, gating, or Environment usage/semantics, defer to installed ClerkKitUI behavior and mirror it.