1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | clerk-setup-clerk-skills |
| 作者/维护者 | Clerk（认证服务提供商，官方组织账号） |
| 来源链接 | https://github.com/clerk/skills/tree/main/skills/core/clerk-setup |
| 许可证 | MIT（README 与 SKILL.md 均声明） |
| GitHub Stars | 66（数据来自 GitHub API；为 clerk/skills 合集仓库整体数字，不代表本技能自身热度） |
| Forks | 4（数据来自 GitHub API，同上口径） |
| 最新版本 | 2.3.0（SKILL.md 内部版本号） |
| 安装方式 | 见第 10 章 |
2. 功能介绍与亮点
clerk-setup 是 Clerk 官方发布的 Agent Skill，用于在任意前端/全栈项目中接入 Clerk 认证服务。核心能力：
- 框架自动识别：读取项目
package.json，自动匹配 Next.js、React、Vue、Nuxt、Astro、TanStack Start、React Router、Express、Fastify、Expo 等 11 种框架/平台，并跳转到对应官方 quickstart 文档。 - Agent 优先的 CLI 流程：通过
clerkCLI 一条命令完成建应用、写入环境变量、安装 SDK（clerk init --framework <fw>），并区分“全新项目”“已有项目接已有 Clerk 应用”“已有项目建新 Clerk 应用”三种典型场景，逐一给出命令序列。 - 迁移引导：内置从 NextAuth/Auth.js、Supabase Auth、Firebase Auth、AWS Cognito、Auth0、Passport.js 等迁移到 Clerk 的检测方法与迁移策略（整体切换 vs 灰度双跑）。
- 常见坑清单：把 Next.js 15
auth()需要await、ClerkProvider必须放在<body>内、中间件 matcher 遗漏 API 路由等实战踩坑点整理成表格，并建议先跑clerk doctor自检。 - 密钥安全提醒：明确警告“切勿在客户端代码中使用 Secret Key，只有
NEXT_PUBLIC_*前缀的 Key 才能出现在客户端”。
亮点：官方出品、更新频繁（最近一次提交在 2026-08-06，两天前）、文档覆盖面广（11 个框架 + 6 类迁移来源 + 常见错误表），且与同仓库内 clerk-nextjs-patterns、clerk-custom-ui、clerk-testing 等技能形成互补，適合作为接入 Clerk 的第一步。
3. 适用场景
所属分类：集成与工作流自动化
适用于需要给应用接入第三方认证服务的开发者：
- 新项目从零搭建登录/注册功能，不想逐字阅读官方文档
- 已有项目想从 NextAuth、Firebase Auth、Auth0 等方案迁移到 Clerk
- 团队使用多种前端框架（Next.js、Vue、Astro 等），需要一份能自动适配框架的接入指南
- 遇到 Clerk 集成报错（中间件、Provider 位置、Node 版本等），需要按图索骥排查
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。官方 README 提供手动安装命令
git clone https://github.com/clerk/skills ~/.claude/skills/clerk。 - Codex：✅ 原生支持。官方 README 提供
codex plugin marketplace add clerk/skills，装好后在/plugins中启用即可。 - OpenClaw：❓ 未验证。官方材料未提及，但技能遵循 Agent Skills 开放规范，理论上可手动放入对应 skills 目录。
- Hermes Agent：❓ 未验证。同上，官方材料未覆盖。
（官方另提供 npx skills add clerk/skills 通用安装方式，Clerk 自己的公告页面称其同时兼容 Cursor、Windsurf、GitHub Copilot、Gemini CLI。）
5. 推荐理由
对初中级开发者而言，“给项目接入认证”往往是最容易踩坑却又必须做对的一步——涉及框架差异、环境变量、中间件位置、Server Component 与 Client Component 的边界等一堆细节。clerk-setup 把这些差异封装成一张框架对照表和一套决策树，agent 读取项目依赖后就能自动挑对文档、按步骤执行，还顺带给出从其他认证方案迁移过来的路径与常见错误自检清单，显著降低了“接错一步导致线上认证失败”的风险。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 发布方 Clerk 是该认证服务的官方所有者（第一方出品）；仓库星数（66，且为合集共享）低于 1k，暂无更高的独立第三方证据 |
| 可用性 | 9 | 一条命令安装，SKILL.md 含 11 框架对照表、决策树、迁移指南与常见坑表格；仓库最近一次提交为 2026-08-06，维护活跃；需注册 Clerk 账号（提供免费额度）作为外部依赖 |
| 安全性 | 8 | 指令范围明确（读取 package.json、按官方文档执行框架标准安装步骤、调用 clerk CLI 完成密钥写入），外联目标仅为 clerk.com 官方文档且透明；主动提示 Secret Key 不得暴露给客户端；License 为 MIT，清晰可查；未发现可疑指令或混淆代码 |
综合评分：8.0（三项均值，≥7.0 达标线）
安全检查清单逐项结果：
① 执行 shell 命令及权限范围：会引导执行 npm install、clerk CLI 相关命令（建应用、写环境变量、生成迁移文件），均为完成认证接入所需的常规操作，范围可解释。
② 运行时联网外发：通过 WebFetch 拉取 clerk.com 官方 quickstart 文档，目标透明。
③ API Key/凭据处理：要求 CLERK_SECRET_KEY 等写入 .env 系列文件，并明确警示不得在客户端代码中使用 Secret Key。
④ 可疑指令：未发现提示词注入或混淆代码迹象。
⑤ 作者信誉：Clerk 为知名认证服务提供商，仓库归属官方 GitHub 组织。
⑥ License：MIT，SKILL.md 与 README 均有明确声明。
⑦ 最近维护：2026-08-06，两天前。
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与 clerk-setup 的差异 |
|---|---|---|
Auth0（auth0/agent-skills） |
Auth0 官方按框架拆分的多个接入技能（React/Next.js/Angular/Vue/React Native/MFA） | 同样是按框架拆分的官方认证接入方案，但 Clerk 版本额外内置“从其他认证服务迁移过来”的检测与策略，Auth0 版本更侧重单一框架的深入接入细节 |
Supabase Auth（supabase/agent-skills） |
作为 Supabase 后端即服务（BaaS）的一部分提供认证能力 | Supabase Auth 与 Postgres 数据库、Row Level Security 深度绑定，适合已用 Supabase 做后端的项目；Clerk 是独立认证服务，不绑定特定数据库 |
Better Auth（better-auth/skills） |
开源、可自托管的 TypeScript 认证库 | Better Auth 需要自己管理数据库 schema 与 Session 存储，更适合希望完全掌控数据、不依赖第三方托管服务的团队；Clerk 走全托管 SaaS 路线，接入更快但依赖 Clerk 的云服务 |
WorkOS（workos/skills） |
面向企业级 SSO / SCIM 场景的认证与身份管理服务 | WorkOS 主打面向企业客户的单点登录与目录同步，Clerk 更偏向消费级/中小团队应用的登录注册与用户管理 |
8. 用户评价
该技能所属仓库 clerk/skills 于 2026 年初创建，GitHub 上暂无具名第三方用户评价或独立评测文章；Clerk 官方在其变更日志中宣布了该技能集，说明其为官方正式发布并持续维护的产品线，但该公告本身来自 Clerk 官方渠道，不构成独立第三方评价。
9. 其他补充
clerk/skills 仓库同时包含 clerk-cli（CLI 日常运维）、clerk-custom-ui（自定义登录界面）、clerk-backend-api（后端 API 浏览与调用）、clerk-orgs（多租户组织）、clerk-billing（订阅计费）、clerk-webhooks（事件同步）、clerk-testing（端到端测试）及 iOS/Android/Expo 原生移动端技能，clerk-setup 是其中面向“首次接入”场景的入口技能。
10. 安装使用方式
- 通用 Agent Skills CLI（跨 Claude Code / Cursor / Windsurf / Copilot / Gemini CLI）：
npx skills add clerk/skills - Claude Code 手动安装：
git clone https://github.com/clerk/skills ~/.claude/skills/clerk - Codex：
安装后重启 Codex，在codex plugin marketplace add clerk/skills/plugins中选择 Clerk Skills 并启用。
安装后注意事项：需在 Clerk Dashboard 注册账号获取 CLERK_SECRET_KEY 与 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY（或框架对应的等价变量），也可依赖 Clerk 的 Keyless 机制在首次运行时自动生成开发环境密钥；触发方式为在会话中提出“给项目加登录/添加认证”一类需求。
11. 注意事项
- 依赖 Clerk 云端账号（提供免费额度，规模化使用需付费套餐），并非完全自托管方案。
- 涉及从其他认证方案迁移时，SKILL.md 给出的是策略性指引（整体切换 vs 灰度双跑），具体的数据导出与密码哈希升级仍需结合 Clerk Backend API 文档操作。
- 仓库整体 star 数（66）反映的是
clerk/skills合集仓库的关注度，不能等同于clerk-setup这一具体技能的采用规模。 - 跨 Agent 兼容性中 OpenClaw 与 Hermes Agent 未获官方材料确认，实际使用前建议先验证。