用途
auth-setup 是 Convex 的代理技能（agent skill），用于在 Convex 项目中实现安全认证，包含用户管理与访问控制。它主要面向以下场景：
- 首次为 Convex 项目配置认证
- 实现用户管理（users 表、身份映射）
- 创建认证辅助函数
- 配置认证提供方（Convex Auth、Clerk、WorkOS AuthKit、Auth0、自定义 JWT）
第一步：先选择认证提供方
资料明确指出，Convex 支持多种认证方式，不要假设使用哪个提供方。在编写配置代码之前：
- 询问用户希望使用哪种认证方案，除非仓库已能明显看出
- 如果仓库已经使用某提供方，则继续使用该提供方，除非用户想切换
- 如果用户尚未选择且仓库没有明显信号，应先询问再继续
常见选项：
- Convex Auth：当用户希望认证直接在 Convex 中处理时，是较好的默认选择
- Clerk：当应用已使用 Clerk，或用户需要 Clerk 的托管认证功能时使用
- WorkOS AuthKit：当应用已使用 WorkOS，或用户明确需要 AuthKit 时使用
- Auth0：当应用已使用 Auth0 时使用
- 自定义 JWT 提供方：当需要集成上述范围之外的现有认证系统时使用
询问之前可先在仓库中寻找信号，例如依赖（@clerk/、@workos-inc/、@auth0/* 或 Convex Auth 相关包）、已有文件（convex/auth.config.ts、认证中间件、provider 包装组件或登录组件）、明确指向某提供方的环境变量。
选择提供方之后
阅读该提供方的官方指南以及匹配的本地参考文件：
- Convex Auth：官方文档，然后 references/convex-auth.md
- Clerk：官方文档，然后 references/clerk.md
- WorkOS AuthKit：官方文档，然后 references/workos-authkit.md
- Auth0：官方文档，然后 references/auth0.md
本地参考文件包含具体工作流、预期文件和環境变量、注意事项与验证检查。可从中获取包安装、客户端 provider 接线、环境变量、convex/auth.config.ts 配置、登录与登出 UI 模式、以及针对 React、Vite 或 Next.js 的框架特定配置。
随后阅读 references/common-patterns.md，了解跨提供方通用的 Convex 端模式：
- 将 ctx.auth.getUserIdentity() 映射到 users 表
- getCurrentUser 与 getCurrentUserOrNull
- requireAdmin 等授权辅助函数
- 所有权检查与团队成员检查
- 公开、私有与混合查询模式
资料提醒：文档可用时，不要凭记忆编造提供方特定配置；不要假设提供方初始化命令就已完成后整个集成，应验证生成的文件并补齐提供方参考文件中指出的初始化后接线步骤。
工作流
- 确定提供方（询问用户或从仓库推断）
- 询问用户当前是要仅本地搭建还是生产级配置
- 阅读匹配的提供方参考文件
- 按官方提供方文档执行当前配置细节
- 应用 references/common-patterns.md 中的共享 Convex 模式
- 仅当应用需要 users 表时，接入 storeUser 或等价的身份同步
- 按需添加所有权、管理员访问或团队访问的授权检查
- 验证登录状态、受保护查询、环境变量，以及被要求时的生产配置
如果流程因交互式提供方或部署配置而阻塞，应明确向用户提出所需的确切人工步骤，待其完成后继续。对于面向 UI 的认证流程，可在配置完成后主动验证真实的注册或登录流程。若环境具备浏览器自动化工具可使用；否则给用户一份简短的人工验证清单。
参考文件
提供方参考：
- references/convex-auth.md
- references/clerk.md
- references/workos-authkit.md
- references/auth0.md
共享模式：
- references/common-patterns.md
检查清单
- 在编写配置代码前已选择正确的认证提供方
- 已阅读相关提供方参考文件
- 已询问用户需要仅本地搭建还是生产级配置
- 提供方特定接线使用了官方提供方文档
- users 表带有 tokenIdentifier 索引
- getCurrentUser 辅助函数
- 用于首次登录的 storeUser mutation
- 所有受保护函数中都有认证检查
- 资源访问有授权检查
- 清晰的错误信息（“Not authenticated”“Unauthorized”）
- 客户端已为所选提供方配置认证 provider
- 如被要求，也覆盖了生产认证配置
限制
资料未提供该技能的独立安装命令、收费方式、适用平台或具体效果数据，这些内容暂未提供。