clerk-setup 是一个为项目添加 Clerk 身份认证的技能，其做法是遵循 Clerk 官方快速入门文档，而不是自行发明配置流程。
用途 当用户提出“添加 Clerk”或“添加认证”等需求时，此技能负责将 Clerk 认证接入项目中。它通过读取项目的 package.json 检测框架，并据此选择对应的官方快速入门指南，然后按步骤执行设置。
主要能力
- 框架检测：读取 package.json 依赖，匹配到对应的框架与快速入门 URL。支持的框架包括 Next.js、Remix、Astro、Nuxt、React Router、TanStack Start、React SPA、Vue、Express、Fastify、Expo。其他平台包括 Chrome 扩展、Android、iOS、Vanilla JavaScript。
- 获取快速入门：使用 WebFetch 获取对应框架的官方快速入门指南，提示词为提取完整设置说明，包括所有代码片段、文件路径和配置步骤。
- 执行设置步骤：按照官方指南执行安装所需包、设置环境变量、添加 Provider/中间件、按需创建登录/注册路由，以及测试集成。
- 开发 API 密钥：提供两种路径。Keyless（自动）：首次 SDK 初始化时，Clerk 自动生成开发密钥并显示“Claim your application”弹窗，无需手动设置密钥；Manual（仪表盘）：若 Keyless 未触发，可从 dashboard.clerk.com 获取密钥，Publishable Key 以 pk_test_ 或 pk_live_ 开头，Secret Key 以 sk_test_ 或 sk_live_ 开头，并设置为环境变量 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY。
- 从其他认证方案迁移：若项目已有认证，先检测现有认证库（next-auth/@auth/core、@supabase/supabase-js、firebase/firebase-admin、@aws-amplify/auth、auth0/@auth0/nextjs-auth0、passport、自定义 JWT/会话实现），再审计当前认证点并制定迁移计划。
使用方式 决策流程为：用户请求“添加 Clerk”或“添加认证”后，读取 package.json；若检测到已有认证，则审计当前认证并创建迁移计划；否则全新安装；随后从依赖中识别框架，WebFetch 对应的快速入门 URL，并逐步遵循官方说明。
适用场景 适用于需要为各类 Web、移动、桌面扩展项目接入 Clerk 认证的场景，尤其是希望按官方快速入门流程标准化接入的开发者。也适用于从 NextAuth、Supabase Auth、Firebase Auth、AWS Cognito、Auth0、Passport.js 或自定义认证迁移到 Clerk 的项目。
迁移注意事项 审计当前认证需识别所有认证触点：登录/注册页面、会话/令牌处理、受保护路由与中间件、用户数据存储（数据库表、外部 ID）、已配置的 OAuth 提供方。迁移计划需考虑：用户数据导出（导出用户并通过 Clerk Backend API 导入）、密码哈希（Clerk 可将哈希透明升级为 Bcrypt）、外部 ID（将旧用户 ID 存为 Clerk 中的 external_id）、会话处理（切换时现有会话将终止）。迁移策略可选：Big bang（一次性切换所有用户，较简单，需要维护窗口）或 Trickle migration（临时运行两套系统，风险较低，复杂度较高）。
常见陷阱
- CRITICAL：Next.js 15+ 中 auth() 为异步，缺少 await，应写 const { userId } = await auth()。
- CRITICAL：暴露 CLERK_SECRET_KEY，切勿在客户端代码中使用密钥，只有 NEXT_PUBLIC_* 密钥是安全的。
- HIGH：缺少中间件 matcher，需包含 API 路由。
- HIGH：ClerkProvider 不在根位置，必须包裹整个应用。
- HIGH：认证路由未公开，需在中间件配置中允许 /sign-in、/sign-up。
- HIGH：落地页要求认证，若需保持“/”公开，应在 matcher 中排除。
- MEDIUM：导入路径错误，服务端代码使用 @clerk/nextjs/server，客户端使用 @clerk/nextjs。
相关主题 包括自定义登录/注册组件、Webhook 到数据库的用户同步、B2B 多租户组织、E2E 测试设置、高级 Next.js 模式。
限制 该技能依赖 Clerk 官方快速入门文档，具体配置细节以官方文档为准；部分高级主题与迁移细节在资料中未提供完整步骤。