AutoGineer
Generated banner for Clerk Swift
Generated logo for Clerk Swift

Clerk Swift

ClerkOfficialCreated by clerk

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
Download ZIP

From the author

Implement Clerk authentication UI in native Swift apps on iOS and macOS with ClerkKitUI prebuilt views or custom ClerkKit flows. Set up Clerk first with the iOS setup prompt, which uses the Clerk CLI. Do not use for Expo or React Native projects.
— the description by clerk

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to implementing Clerk authentication in native Swift projects. It guides developers through the initial setup using the Clerk CLI and offers two distinct paths for UI implementation: prebuilt ClerkKitUI views for rapid integration or custom flows using ClerkKit primitives for full control. The skill emphasizes maintaining existing project configurations, such as custom key loading and established capabilities, while ensuring authentication flows remain consistent with Clerk's native standards.

What it does

  • Configures Clerk SDK and native app registration via the Clerk CLI.
  • Implements prebuilt ClerkKitUI components for standard authentication flows.
  • Supports custom authentication flows using ClerkKit primitives for tailored UX.
  • Ensures runtime environment gating for dynamic authentication requirements.
  • Maintains existing project setup, including custom publishable key loading.
  • Verifies integration through targeted prerequisite checks and build validation.

When to use it

  • When adding authentication to a native Swift iOS or macOS application.
  • When you need to choose between rapid prebuilt UI or highly customized auth screens.
  • When you need to ensure your auth flow respects Clerk's environment settings dynamically.
  • When you need to integrate native Sign in with Apple alongside Clerk.

Advantages

  • Provides a clear decision path between prebuilt and custom implementation.
  • Preserves existing project architecture and custom key loading mechanisms.
  • Ensures UI parity with ClerkKitUI standards for custom flows.
  • Automates prerequisite checks and configuration via CLI tools.
  • Prevents common pitfalls like hardcoding keys or breaking existing app navigation.

Usage examples

“I need to add Clerk authentication to my new native Swift iOS app. How do I start?”
The agent will verify the project is native Swift, guide you through the Clerk CLI setup process to install the SDK and register the app, and then ask if you prefer a prebuilt or custom UI flow.
“I want to use the prebuilt Clerk UI in my SwiftUI app. What should I do?”
The agent will confirm Clerk is set up, ensure the ClerkKitUI package is linked, and provide code to implement AuthView in a sheet and UserButton for the signed-out state.
“I need a custom sign-in flow for my app that matches my brand. Can I use Clerk?”
The agent will guide you through using ClerkKit primitives, ensuring your custom screens follow the necessary step progression and environment gating logic to remain functional.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/clerk/clerk-swift/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip clerk-swift.zip -d .agents/skills

Documentation by clerk

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?

TaskReference
Prebuilt AuthView / UserButton (fastest)references/prebuilt.md
Custom API-driven auth flows (full control)references/custom.md

Quick Start

StepAction
1Confirm the project is native Swift and not Expo/React Native
2If Clerk isn't set up, follow the iOS setup prompt first (see above)
3Determine the flow type (prebuilt or custom); ask if it's undecided, then load the matching reference
4Check the prerequisites the selected flow needs, such as a package product or capability, and make only the targeted changes that are missing
5Implement the flow by following the selected reference
6Build the target and report what remains unverified

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:

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.

Use CaseSource of Truth in Installed Package
SDK products, platform support, and dependency constraintsPackage manifest and target product definitions for ClerkKit and ClerkKitUI
Auth flow sequencing and gatingClerkKitUI AuthView implementation and how it reads the injected Clerk instance's environment
Native Sign in with AppleApple sign-in behavior in the selected flow reference

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

LevelIssuePrevention
CRITICALDoing setup by hand when Clerk isn't set upFollow the iOS setup prompt; it runs the Clerk CLI. Use the manual quickstart only when the CLI can't set up the project
CRITICALAsking the user to paste a publishable keyThe CLI provides it during setup; keep an existing app's own key loading
CRITICALReplacing custom key loading or existing setupKeep the existing Clerk.configure, packages, and capabilities; add only what's missing
CRITICALStarting UI implementation before the flow type is confirmedConfirm the flow first and load the matching reference
CRITICALCustom flow layout diverges from AuthView without explicit requestKeep custom screens materially close to AuthView structure and step composition by default
CRITICALCollapsing custom auth into a single all-fields screenFollow AuthView-style multi-step progression and step-specific field collection
CRITICALGuessing custom sequencing or gating when uncertainReference installed ClerkKitUI behavior and mirror it
HIGHHardcoding this instance's current settings into custom flow codeGate steps at runtime from the injected Clerk instance's environment, as AuthView does
HIGHUsing this skill for Expo/React NativeDetect and route away before implementation

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

Files

references/custom.md

Custom Flow Reference (ClerkKit)

Use this file only when flow type is custom.

Purpose

Implement native iOS auth with ClerkKit primitives while keeping flow and layout very close to ClerkKitUI AuthView by default.

Prerequisites

Clerk must already be set up through the iOS setup prompt (or the manual iOS quickstart when the CLI can't set up the project). Then check only what this flow adds, and make targeted changes for anything missing:

  1. Package products

  • The app target needs ClerkKit. Leave an already linked ClerkKitUI in place, and don't add it unless the developer asks for mixed prebuilt and custom composition.

  • Don't change the existing clerk-ios version requirement.

  1. Sign in with Apple

  • If native Sign in with Apple is enabled for this app, the target needs the Sign in with Apple capability. npx -y clerk@latest doctor reports the Apple connection and whether each configuration has the entitlement.

  • To enable it, run npx -y clerk@latest init --sign-in-with-apple --json from the project directory. It configures Clerk and adds the entitlement. If the CLI isn't available, add the capability in Xcode.

These init commands need a linked project. With --json, an unlinked project returns status: "application-required": rerun with --app <application_id> for the application whose publishable_key matches the app's existing key, from npx -y clerk@latest apps list --json.

Keep the existing Clerk.configure call, its key loading, and existing capabilities.

Source-Driven Requirements

When flow details are unclear, read the installed package source from Xcode DerivedData:

  • ~/Library/Developer/Xcode/DerivedData/.../SourcePackages/checkouts/clerk-ios

Source priority rules for custom flow:

  • Primary source: installed ClerkKitUI source for auth UI behavior and gating parity.

  • Secondary source: installed ClerkKit source for core auth/network/config behavior.

  • Fallback only: example apps (local or GitHub) when behavior is unclear from library source.

For custom flows, treat ClerkKitUI AuthView as a strict parity target for:

  • step progression/sequencing

  • field visibility and hidden-state rules per step

  • branching between factors/strategies

  • screen structure and layout composition per step

  • view hierarchy and section ordering per step

Required Patterns

  1. Runtime environment gating

  • Read the instance's settings at runtime from the injected Clerk instance's environment, as AuthView does: @Environment(Clerk.self) private var clerk, then clerk.environment (for example clerk.environment?.userSettings).

  • Gate identifiers, factors, social and Apple sign-in, and required sign-up fields on those values, using the same fields and semantics as ClerkKitUI.

  • Don't hardcode the instance's current settings into the flow, and don't call /v1/environment directly. Settings can change in the Clerk Dashboard without an app update.

  1. Combined-entry default

  • Keep a combined sign-in-or-sign-up entry by default.

  • Do not add a local sign-in/sign-up mode switcher unless explicitly requested.

  1. AuthView progression parity

  • Follow ClerkKitUI AuthView progression logic for advancing/regressing steps.

  • Show/hide inputs exactly according to the active step requirements instead of static form layouts.

  • Keep factor/strategy branching aligned with how AuthView gates transitions.

  • Keep screen layout and component structure very close to AuthView defaults unless the developer explicitly requests a different UX.

  • Keep view hierarchy and section ordering close to AuthView on each step; do not redesign the information architecture unless explicitly requested.

  • Break the custom flow into multiple step screens/states similar to AuthView; do not try to gather all signup/signin requirements in one view.

  • If proposed custom layout materially deviates from AuthView, stop and ask for explicit developer approval before implementing.

  1. Multi-file organization and separation of concerns

  • Break custom auth flow into focused files/modules instead of one large screen file.

  • Separate UI step views, flow/state orchestration, and Clerk/network integration responsibilities.

  • Keep per-file responsibilities narrow and composable so new factors/steps can be added without rewriting a monolithic view.

  1. Required-field coverage

  • Collect every sign-up field the environment marks as required, at the step where AuthView collects it.

  • Handle missing requirements the sign-up reports after each step instead of assuming a fixed field list.

  1. Apple sign-in policy

  • Implement Apple via native Clerk Apple path.

  • Do not implement Apple through generic social-provider OAuth handling.

  1. Source parity

  • Follow installed ClerkKitUI and ClerkKit source patterns for sequencing, factor handling, and verification steps.

  • When unsure about custom-flow implementation details, sequencing, gating, or Environment usage/semantics, stop guessing and reference installed ClerkKitUI implementation behavior.

  • Resolve ambiguity by mirroring ClerkKitUI behavior unless the developer explicitly asks for a different approach.

Verification Checklist

  1. Prerequisites are in place

  • ClerkKit is linked to the app target.

  • If native Sign in with Apple is enabled, the target has the Sign in with Apple capability.

  • Existing setup and custom key loading are unchanged.

  1. No unrequested mode switcher

  • No local toggle/segmented control/tabs for sign-in vs sign-up unless explicitly requested.

  1. Runtime gating

  • Available identifiers, factors, and providers come from the injected Clerk instance's environment at runtime, not hardcoded values.

  • Environment fields used for gating and requirements match the set and semantics used by installed ClerkKitUI.

  1. AuthView flow parity

  • Step transitions follow AuthView progression rules.

  • Inputs shown at each step match AuthView step-level visibility behavior.

  • Step layouts and component grouping are materially close to AuthView; do not introduce major layout redesign unless explicitly requested.

  • View hierarchy/section ordering remain close to AuthView across steps unless explicitly requested otherwise.

  • Flow is split across multiple steps like AuthView; required data is not collected in one monolithic screen.

  • When implementation ambiguity appears, final behavior matches installed ClerkKitUI rather than an inferred/custom interpretation.

  1. Flow organization quality

  • Custom flow code is split into multiple focused files/modules (not a single monolithic auth view file).

  • UI, state/flow orchestration, and integration logic are separated with clear boundaries.

  1. Required fields covered

  • Every sign-up field the environment marks as required is collected.

  1. Apple path correctness

  • Apple flow uses native path, not generic provider OAuth path.

  1. No unrequested prebuilt dependency

  • ClerkKitUI is not added unless explicitly needed.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs Node.js

The author says: Requires Xcode and ClerkKit Swift package

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
clerk
Publisher
Clerk (Official)
Source
clerk/skills · skills/clerk-swift · commit c5d2c0d
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by clerk or Clerk.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download clerk-swift.zip