Clerk Swift

ClerkOfficialCreated by clerk

Skill
Tool integration
Software development
MIT
Low risk

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

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/clerk/clerk-swift/download

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?

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

Quick Start

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

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.

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

Workflow

Detect native Swift vs Expo/React Native.
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.
If the flow type isn't known, ask for prebuilt or custom.
Load the matching flow reference.
Check that flow's prerequisites and make only the missing, targeted changes, preserving completed setup and custom key loading.
Implement using the selected reference.
Verify using the selected reference, then build the target.

Common Pitfalls

Level	Issue	Prevention
CRITICAL	Doing setup by hand when Clerk isn't set up	Follow the iOS setup prompt; it runs the Clerk CLI. Use the manual quickstart only when the CLI can't set up the project
CRITICAL	Asking the user to paste a publishable key	The CLI provides it during setup; keep an existing app's own key loading
CRITICAL	Replacing custom key loading or existing setup	Keep the existing `Clerk.configure`, packages, and capabilities; add only what's missing
CRITICAL	Starting UI implementation before the flow type is confirmed	Confirm the flow first and load the matching reference
CRITICAL	Custom flow layout diverges from `AuthView` without explicit request	Keep custom screens materially close to `AuthView` structure and step composition by default
CRITICAL	Collapsing custom auth into a single all-fields screen	Follow `AuthView`-style multi-step progression and step-specific field collection
CRITICAL	Guessing custom sequencing or gating when uncertain	Reference installed `ClerkKitUI` behavior and mirror it
HIGH	Hardcoding this instance's current settings into custom flow code	Gate steps at runtime from the injected Clerk instance's `environment`, as `AuthView` does
HIGH	Using this skill for Expo/React Native	Detect and route away before implementation

Files

ATTRIBUTION.mdAdded by AutoGineer827 B
SKILL.md7.5 KiB
evals/evals.json2.6 KiB
references/custom.md6.9 KiB
references/prebuilt.md3.0 KiB

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:

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.

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

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.

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.

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.

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.

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.

Apple sign-in policy

Implement Apple via native Clerk Apple path.
Do not implement Apple through generic social-provider OAuth handling.

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

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.

No unrequested mode switcher

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

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.

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.

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.

Required fields covered

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

Apple path correctness

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

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

2026-11-08

AutoGineer is not affiliated with or endorsed by clerk.

Download ZIP

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