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.

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.

Workflow

1. Detect native iOS/Swift vs Expo/React Native.
2. If flow type is not explicitly provided, ask user for prebuilt or custom.
3. If publishable key is not explicitly provided, ask user for it.
4. Wait for both answers before changing files.
5. Load matching flow reference file.
6. Ensure publishable key is valid and directly wired in Clerk.configure.
7. Ensure package install/products match selected flow and package requirement follows latest up-to-next-major policy when newly added.
8. Inspect installed ClerkKitUI source to map Environment fields used for gating/required behavior in the selected flow.
9. Call /v1/environment and interpret response through the step 8 field map.
10. Find iOS quickstart URL from installed clerk-ios package README, append .md, then visit and read it.
11. Build quickstart checklist from the visited markdown quickstart, detect missing required setup, and apply the missing setup in the current project.
12. Ensure the quickstart associated-domain capability step is fully applied (webcredentials:{YOUR_FRONTEND_API_URL} when missing).
13. Implement using selected reference checklist.
14. Verify using selected reference checklist plus shared gates.

Common Pitfalls

See Also

• ../clerk/SKILL.md for top-level Clerk routing
• ../setup/SKILL.md for non-native or cross-framework setup
• installed clerk-ios package README.md (source for current iOS quickstart link)
• https://github.com/clerk/clerk-ios