clerk-swift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clerk Swift (Native iOS)

Clerk Swift（原生iOS）

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

本技能通过读取已安装包的源码并镜像当前ClerkKit/ClerkKitUI的行为，在原生Swift/iOS项目中集成Clerk。

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.

当满足以下任一条件时激活本技能：

用户明确询问Swift、SwiftUI、UIKit或原生iOS的Clerk实现方式
项目为原生iOS/Swift项目（例如包含
```
.xcodeproj
```
、
```
.xcworkspace
```
、
```
Package.swift
```
、Swift目标文件）

当满足以下任一条件时请勿激活本技能：

项目为Expo项目
项目为React Native项目

如果检测到Expo/React Native相关信号，请将请求路由到通用设置技能，而非本技能。

Quick Start

快速开始

Step	Action
1	Confirm project type is native Swift/iOS and not Expo/React Native
2	Determine flow type ( `prebuilt` or `custom` ) and load the matching reference file
3	Ensure a valid publishable key exists (or ask developer) and wire it directly in configuration
4	Ensure `clerk-ios` package is installed with correct products for selected flow; if missing, install latest available release using an up-to-next-major version requirement
5	Inspect installed `ClerkKitUI` source to identify which `Environment` fields drive feature/step gating
6	Call `/v1/environment` after step 5 and evaluate only against the `ClerkKitUI` -aligned field map
7	Find the iOS quickstart URL in the installed `clerk-ios` package README, append `.md` , then visit and read the markdown URL to compile a required-step checklist
8	Verify and complete all quickstart prerequisites for this project (for example associated domains and required capabilities)
9	Implement flow by following only the selected reference checklist

步骤	操作
1	确认项目类型为原生Swift/iOS，且非Expo/React Native
2	确定流程类型（ `prebuilt` 或 `custom` ）并加载对应的参考文件
3	确保存在有效的publishable key（若缺失则向开发者索要），并直接在配置中配置该密钥
4	确保已安装 `clerk-ios` 包，且包产品与所选流程匹配；若未安装，则使用“兼容下一个大版本”的版本要求安装最新可用版本
5	检查已安装的 `ClerkKitUI` 源码，识别哪些 `Environment` 字段用于控制功能/步骤的启用状态
6	完成步骤5后调用 `/v1/environment` 接口，并仅根据与 `ClerkKitUI` 对齐的字段映射来解析响应
7	在已安装的 `clerk-ios` 包的README中找到iOS快速开始链接，追加 `.md` 后缀后访问并读取该Markdown页面，整理出必要步骤清单
8	验证并完成该项目的所有快速开始前置条件（例如关联域名和所需权限）
9	严格按照所选参考清单实现流程

Decision Tree

决策树

text

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

text

用户询问Swift/iOS中的Clerk集成
    |
    +-- 检测到Expo/React Native项目？
    |     |
    |     +-- 是 -> 请勿使用本技能
    |     |
    |     +-- 否 -> 继续
    |
    +-- 检测到已有认证UI？
    |     |
    |     +-- 检测到预构建视图 -> 加载references/prebuilt.md
    |     |
    |     +-- 检测到自定义流程 -> 加载references/custom.md
    |     |
    |     +-- 全新实现 -> 询问开发者选择预构建还是自定义流程，然后加载对应参考文件
    |
    +-- 确保publishable key已配置且直接写入
    |
    +-- 确保已安装clerk-ios包
    |
    +-- 检查ClerkKitUI Environment字段的使用方式
    |
    +-- 使用步骤5的字段映射调用/v1/environment接口
    |
    +-- 访问并读取已安装clerk-ios包README中的快速开始链接
    |
    +-- 验证所有快速开始前置条件已完成
    |
    +-- 根据所选流程参考实现集成

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.

确定流程类型后，仅加载以下其中一个参考文件：

预构建流程：references/prebuilt.md
自定义流程：references/custom.md

除非开发者明确要求混合实现，否则请勿在单次实现中混用两个参考文件的内容。

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.

在进行任何实现编辑之前，Agent必须获取以下两项信息：

流程选择：
```
prebuilt
```
或
```
custom
```
有效的Clerk publishable key

如果用户请求/上下文缺失任一信息：

向用户询问缺失的信息
暂停操作等待用户回复
在获取回复前请勿编辑文件或安装依赖

仅当用户在本次对话中已明确提供相关信息时，才可跳过询问步骤。

Source-Driven Templates

源码驱动模板

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

Use Case	Source of Truth in Installed Package
SDK package products, platform support, and dependency constraints	Package manifest and target product definitions for `ClerkKit` and `ClerkKitUI` , plus package requirement style (up-to-next-major)
Publishable key validation and frontend API derivation	Clerk configuration logic (search symbols: `configure(publishableKey` , `frontendApiUrl` , `invalidPublishableKeyFormat` )
Environment endpoint contract and field semantics	Environment request path and request construction plus `ClerkKitUI` `Environment` field usage for gating (search symbols: `/v1/environment` , `Request<Clerk.Environment>` , `Environment` usage in `ClerkKitUI` )
iOS quickstart requirements	Installed `clerk-ios` package README quickstart link plus the visited/read quickstart page checklist steps (including project setup prerequisites)
Native Sign in with Apple implementation	Apple capability and native sign-in behavior in selected flow reference

请勿在本技能中硬编码实现示例。在实现前必须检查当前已安装包的源码。

使用场景	已安装包中的事实来源
SDK包产品、平台支持和依赖约束	`ClerkKit` 和 `ClerkKitUI` 的包清单与目标产品定义，以及包版本要求风格（兼容下一个大版本）
Publishable key验证和前端API推导	Clerk配置逻辑（搜索符号： `configure(publishableKey` , `frontendApiUrl` , `invalidPublishableKeyFormat` ）
环境端点契约和字段语义	环境请求路径与请求构造，以及 `ClerkKitUI` 中用于控制启用状态的 `Environment` 字段使用方式（搜索符号： `/v1/environment` , `Request<Clerk.Environment>` , `ClerkKitUI` 中的 `Environment` 用法）
iOS快速开始要求	已安装 `clerk-ios` 包README中的快速开始链接，以及访问并读取该快速开始页面的清单步骤（包括项目设置前置条件）
原生Apple登录实现	所选流程参考中的Apple权限配置和原生登录行为

Execution Gates (Do Not Skip)

执行门限（请勿跳过）

No implementation edits before prerequisites

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

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.

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.

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.

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.

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)

Reference-file discipline is mandatory

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

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}

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.

完成前置条件前请勿进行实现编辑

在确认流程类型并获取有效publishable key前，请勿编辑项目文件。

缺失流程或密钥必须触发询问

若缺失流程选择，明确询问：使用预构建视图还是自定义流程？
若publishable key缺失/为占位符/无效，明确索要真实密钥。
在获取两项回复前请勿继续操作。

必须采用直接配置publishable key的方式

将开发者提供的publishable key直接写入传递给
```
Clerk.configure
```
的应用配置中。
除非开发者明确要求，否则请勿引入plist/本地密钥/环境变量/构建设置等间接配置方式。

必须遵循包安装/版本策略

若未安装
```
clerk-ios
```
，则安装最新可用版本，并使用“兼容下一个大版本”的版本要求。
除非开发者明确要求固定版本，否则请勿固定精确的包版本。

必须检查ClerkKitUI Environment字段

安装包后，检查已安装的
```
ClerkKitUI
```
源码，识别所选流程中哪些
```
Environment
```
字段控制认证行为的启用状态。
在调用
```
/v1/environment
```
接口前，构建Agent内部的字段映射表。

必须调用环境接口（两种流程均需）

仅在完成包安装和步骤5的字段映射表构建后，才可直接调用
```
/v1/environment
```
HTTP接口。
使用与
```
ClerkKitUI
```
对齐的字段映射表，将响应传入所选参考工作流：
- 预构建流程：使用响应判断是否启用Apple登录以及是否需要修改权限
- 自定义流程：仅在Agent内部进行完整的标准化/矩阵处理（切勿将矩阵 artifacts 持久化到项目代码中）

必须遵循参考文件规范

确定流程类型后，仅根据所选流程参考文件进行实现和验证。

必须符合快速开始要求

在已安装的
```
clerk-ios
```
包README中找到iOS快速开始链接，追加
```
.md
```
后缀后访问并读取该Markdown页面。
在完成任务前，对照快速开始页面的清单步骤检查项目。
若缺失必要的快速开始设置，在完成任务前补全这些设置。
这包括添加所有缺失的关联域名条目和其他快速开始要求的应用权限。
必须执行快速开始中的“添加关联域名权限”步骤（
```
https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability
```
），并确保关联域名条目符合快速开始要求（
```
webcredentials:{YOUR_FRONTEND_API_URL}
```
）。

自定义流程必须与AuthView结构保持一致

对于
```
custom
```
流程，布局和流程结构必须与ClerkKitUI
```
AuthView
```
的默认结构基本一致。
若开发者未明确要求不同的用户体验，请勿引入与
```
AuthView
```
差异较大的结构/布局改动。
若对自定义流程的步骤顺序、启用状态控制或
```
Environment
```
用法/语义存在疑问，请参考已安装的
```
ClerkKitUI
```
行为并镜像实现。

Workflow

工作流

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

检测项目类型为原生iOS/Swift还是Expo/React Native。
若用户未明确提供流程类型，询问用户选择
```
prebuilt
```
还是
```
custom
```
。
若用户未明确提供publishable key，向用户索要。
在获取两项回复前请勿修改文件。
加载对应的流程参考文件。
确保publishable key有效，并直接写入
```
Clerk.configure
```
的配置中。
确保包安装/产品与所选流程匹配，且新安装时遵循最新的“兼容下一个大版本”版本要求。
检查已安装的
```
ClerkKitUI
```
源码，映射所选流程中用于控制启用状态/必要行为的
```
Environment
```
字段。
调用
```
/v1/environment
```
接口，并通过步骤8的字段映射表解析响应。
在已安装的
```
clerk-ios
```
包README中找到iOS快速开始链接，追加
```
.md
```
后缀后访问并读取该页面。
从访问的Markdown快速开始页面构建检查清单，检测缺失的必要设置，并在当前项目中补全。
确保已完整应用快速开始中的关联域名权限步骤（缺失时添加
```
webcredentials:{YOUR_FRONTEND_API_URL}
```
）。
根据所选流程参考清单进行实现。
根据所选流程参考清单和通用执行门限进行验证。

Common Pitfalls

常见陷阱

Level	Issue	Prevention
CRITICAL	Not asking for missing flow choice before implementation	Ask for `prebuilt` vs `custom` and wait before edits
CRITICAL	Not asking for missing publishable key before implementation	Ask for key and wait before edits
CRITICAL	Starting implementation before flow type is confirmed	Confirm flow first and load matching reference
CRITICAL	Using plist/local/env indirection for publishable key without request	Wire key directly in configuration by default
CRITICAL	Skipping `/v1/environment` call before implementation	Always call environment endpoint for both prebuilt and custom flows
CRITICAL	Calling `/v1/environment` before package install + ClerkKitUI `Environment` field inspection	Install `clerk-ios` first, inspect ClerkKitUI `Environment` usage, then call endpoint
HIGH	Installing `clerk-ios` with exact/stale version by default	If missing, install latest available release using up-to-next-major requirement
CRITICAL	Skipping quickstart prerequisite audit	Visit/read quickstart URL from installed `clerk-ios` package README and verify all required setup steps are completed
CRITICAL	Detecting missing quickstart capabilities/domains but not applying them	Add all missing required quickstart capabilities and Associated Domains before completing
CRITICAL	Skipping quickstart associated-domain capability step	Execute quickstart `Add associated domain capability` and ensure `webcredentials:{YOUR_FRONTEND_API_URL}` is present
CRITICAL	Writing capability/required-field matrices into app code	Keep matrices agent-internal and only apply resulting behavior in UI/auth flow code
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/gating/ `Environment` usage when uncertain	Reference installed `ClerkKitUI` behavior and mirror it for final implementation
HIGH	Using this skill for Expo/React Native	Detect and route away before implementation

级别	问题	预防措施
严重	实现前未询问缺失的流程选择	询问用户选择预构建还是自定义流程，等待回复后再进行编辑
严重	实现前未询问缺失的publishable key	向用户索要密钥，等待回复后再进行编辑
严重	未确认流程类型即开始实现	先确认流程类型，再加载对应的参考文件
严重	未经过请求就使用plist/本地密钥/环境变量等间接方式配置publishable key	默认直接将密钥写入配置中
严重	实现前跳过 `/v1/environment` 接口调用	预构建和自定义流程均必须调用环境接口
严重	在包安装和ClerkKitUI `Environment` 字段检查前调用 `/v1/environment` 接口	先安装 `clerk-ios` 包，检查ClerkKitUI `Environment` 用法，再调用接口
高	默认安装精确/过时版本的 `clerk-ios` 包	若未安装，使用“兼容下一个大版本”的要求安装最新可用版本
严重	跳过快速开始前置条件检查	访问并读取已安装 `clerk-ios` 包README中的快速开始链接，验证所有必要设置步骤已完成
严重	检测到缺失快速开始权限/域名但未补全	在完成任务前添加所有缺失的必要快速开始权限和关联域名
严重	跳过快速开始中的关联域名权限步骤	执行快速开始中的“添加关联域名权限”步骤，并确保 `webcredentials:{YOUR_FRONTEND_API_URL}` 已配置
严重	将权限/必要字段矩阵写入应用代码	仅在Agent内部保留矩阵信息，仅将最终行为应用到UI/认证流程代码中
严重	未经明确请求，自定义流程布局偏离 `AuthView`	默认保持自定义界面与 `AuthView` 的结构和步骤组合基本一致
严重	将自定义认证流程合并为单一全字段界面	遵循 `AuthView` 风格的多步骤流程和分步字段收集方式
严重	对自定义流程的步骤顺序/启用状态/ `Environment` 用法存疑时进行猜测	参考已安装的 `ClerkKitUI` 行为并镜像实现
高	将本技能用于Expo/React Native项目	提前检测项目类型并路由到对应技能