前言¶
在 TypeScript 或 JavaScript 项目里接入登录、注册和会话，往往需要同时处理数据库适配器、框架路由、OAuth 回调、客户端 SDK 和迁移脚本，文件多且步骤容易漏。Better Auth 本身把认证能力收敛到一套配置里，但从零接线仍要对照文档在多处改代码。create-auth 是面向编码助手的 Agent Skill，把「先摸清项目、再定方案、最后按框架落地」写成固定流程，适合在新项目、存量项目或从其他认证库迁移时使用。
这是什么¶
create-auth 由 Better Auth 官方 skills 仓库 提供，在 officialskills.sh 上归类为官方开发类 Skill。它的定位是：在 TS/JS 应用中用 Better Auth 脚手架化实现认证——自动识别框架与数据库、配置适配器与路由处理器、接入 OAuth、并生成认证相关 UI 页面。具体语法与 API 以 better-auth.com/docs 为准。
核心功能¶
Skill 把工作拆成两个阶段，且 Phase 1 规划必须在写实现代码之前完成。
项目扫描（自动推断默认值）¶
助手会分析代码库，尽量从现有文件推断：
- 框架：如
next.config、svelte.config、nuxt.config、astro.config、vite.config，或 Express / Hono 入口。 - 数据库与 ORM：如
prisma/schema.prisma、drizzle.config.ts（含dialect）、package.json中的pg、postgres、mysql2、better-sqlite3、mongoose等依赖；Drizzle 驱动包可进一步区分 Postgres 接入方式。 - 已有认证：
package.json或 import 中的next-auth、lucia、clerk、supabase/auth、firebase/auth等。 - 包管理器：
pnpm-lock.yaml、yarn.lock、bun.lockb、package-lock.json。
能确定的项会用来预填选项，减少重复提问。
结构化规划（AskQuestion）¶
在单次调用中尽量问完适用问题（已能从扫描得出的可跳过），标题可类似「Auth Setup Planning」。覆盖范围包括：
- 项目类型：全新项目 / 在现有项目加认证 / 从其他库迁移
- 框架：Next.js（App 或 Pages Router）、SvelteKit、Nuxt、Astro、Express、Hono、SolidStart 等
- 数据库与 ORM：PostgreSQL / MySQL / SQLite / MongoDB，配合 Prisma、Drizzle 或原生驱动
- 登录方式（可多选）：邮箱密码、社交 OAuth、Magic link、Passkey、手机号
- 社交提供商（选 OAuth 时追问）：Google、GitHub、Apple、Microsoft、Discord、Twitter/X
- 邮箱验证（选邮箱密码时）
- 发信方式（需要验证或密码重置时）：Resend 或暂时 Mock（console）
- 扩展能力（可多选）：2FA、组织/团队、管理后台、API Bearer Token、密码重置等
- 需要的认证页面：登录、注册，以及忘记密码、重置密码、邮箱验证等（随前面选项变化）
- 认证页 UI 风格：极简、居中卡片、分栏、玻璃拟态或自定义描述
回答汇总后，助手会输出一份 Markdown 检查清单式的 Auth Implementation Plan，并请用户确认后再进入实现阶段。
实现路径（Phase 2）¶
用户确认计划后，按决策树执行：
- 新项目：安装
better-auth及计划中的 scoped 包 →auth.ts/auth-client.ts→ 路由处理器 → 环境变量 → CLI migrate/generate → 插件与 UI 页面。 - 迁移：审计现有认证、增量迁移、与旧库并行安装、先路由再会话再 UI、最后移除旧库（文档中有迁移指引）。
- 存量项目加认证：分析结构、安装与配置、路由与 schema 迁移、接入现有页面与插件。
实现结束后，Skill 要求引导用户完成 OAuth 凭据、部署环境变量、端到端测试等后续步骤。
依赖与环境变量（实现时会用到）¶
核心包：
npm install better-auth
按需选用的 scoped 包示例：@better-auth/passkey、@better-auth/sso、@better-auth/stripe、@better-auth/scim、@better-auth/expo。
常见环境变量：
BETTER_AUTH_SECRET=<32+ chars, generate with: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<your database connection string>
OAuth 需额外配置如 GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GOOGLE_CLIENT_ID 等。
服务端配置通常放在 lib/auth.ts 或 src/lib/auth.ts，至少包含 database 与 emailAndPassword: { enabled: true }；标准场景还会配置 socialProviders、邮箱验证与密码重置回调等。计划中提到的 schema 生成与迁移可通过 CLI（资料示例：npx auth@latest，auth 包随 CLI 使用、无需全局安装）配合框架路由（如 Next.js App Router 的 app/api/auth/[...all]/route.ts）完成。
安装与启用¶
在支持 Agent Skills 的助手中，可按 officialskills.sh 所列方式添加：
npx skills add https://github.com/better-auth/skills --skill better-auth-create-auth
也可直接向助手提供 Skill 目录链接，请求安装：
https://github.com/better-auth/skills/tree/main/better-auth/create-auth
安装后，在对话中说明要为项目增加登录/注册或迁移认证即可触发该 Skill 的流程。Cursor、Codex CLI、Claude Code 等对 Skills 的安装入口可能不同，但 Skill 本体均为仓库中的 SKILL.md 指令；未在官方页面单独列出的客户端差异此处不展开。
典型用法¶
下列场景来自官方 Skill 页面「When to use it」说明，对应用法是在已安装 Skill 的会话里用自然语言描述同类需求，由助手执行 Phase 1 扫描与提问，确认计划后落地代码。
- 在 Next.js App Router + Prisma 项目上增加邮箱密码登录。
- 在 SvelteKit 中配置 Google 与 GitHub OAuth。
- 从 NextAuth 或 Lucia 迁移到 Better Auth，尽量降低打断。
- 在 Drizzle schema 上同时启用 2FA、组织（organization） 等插件。
- 为 Hono API 生成带会话保护的登录/注册页，并接好路由处理器。
规划阶段产出的计划示例结构（框架、数据库、登录方式、插件、UI 步骤列表）与资料中的 checklist 一致；实现阶段会按你选的框架生成 auth-client（如 React 客户端）与对应 route handler。
适用场景与注意¶
适合：TypeScript/JavaScript 全栈或前后端分离项目；需要邮箱密码、OAuth、2FA、组织等多能力组合；希望助手按仓库约定一次性串起适配器、路由、迁移与页面，而不是自己拼文档片段。
注意：
- 必须先完成规划并用户确认，再写实现，避免与项目栈不一致。
- 若项目已有其他认证库，迁移路径要求分步并行，勿在未审计前直接删除旧依赖。
- Passkey、企业 SSO、Stripe、SCIM、Expo 等需额外 scoped 包，并在计划中显式选中。
- 邮件相关能力需配置真实发信（如 Resend）或接受开发期 Mock。
- 代码细节以 Better Auth 官方文档为准；Skill 负责流程与决策树，不替代阅读 OAuth 提供商控制台与生产环境密钥管理。
结尾¶
create-auth 把 Better Auth 接入拆成「扫描 → 一问一答式规划 → 确认清单 → 分场景实现」，覆盖多框架、多数据库与从旧库迁移。若你正在用 AI 编码助手搭登录体系，可从官方仓库安装 Skill，并在会话中直接描述目标栈与登录方式。
官方地址：https://github.com/better-auth/skills/tree/main/better-auth/create-auth
