К основному содержанию
скилл CX Codex

better-auth · oakoss — скилл для Claude Code: что делает и как установить

Скилл для Claude Code подгружает агенту справочник по better-auth: конфиг, плагины, стратегии сессий и типовые ошибки. Даёт справку при настройке входа, 2FA и организаций.

MIT 114 установок ★ 29 обновлён 2026-08-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add oakoss/agent-skills --skill better-auth -a claude-code
Открыть на GitHub

Что делает better-auth

Скилл даёт агенту справочник по better-auth, self-hosted фреймворку аутентификации на TypeScript с соцвходом, 2FA, passkey и организациями. Внутри таблицы переменных окружения и опций конфига, каталог плагинов от organization и admin до sso, scim и stripe, три стратегии сессий. Скилл собран под [email protected]; с 1.4.0 пакет выходит только в ESM.

Отдельный блок — антипаттерны, на которых спотыкаются чаще всего. d1Adapter брать не стоит: с D1 работают через Drizzle или Kysely с provider: "sqlite". На TanStack Start tanstackStartCookies() обязан идти последним плагином в массиве. Проверять вход нужно по session?.user, потому что сам объект сессии всегда truthy.

Для запуска нужны BETTER_AUTH_SECRET длиной от 32 символов и BETTER_AUTH_URL. CLI ищет auth.ts только в ./, ./lib, ./utils и ./src; положите конфиг в другое место — генерация его не увидит. После правки списка плагинов схему перегенерируют командой npx @better-auth/cli@latest generate. Для Cloudflare Workers в wrangler.toml нужен флаг nodejs_compat, без него сборка упирается именно в него.

Какие задачи решает

  • подключить вход через Google и другие соцсети
  • включить TOTP и резервные коды для аккаунтов
  • развести арендаторов по организациям с ролями
  • перевести проект с NextAuth или Clerk на self-hosted схему
  • починить падающий d1Adapter на Cloudflare D1

Примеры запросов агенту

  • Настрой better-auth в проекте на Next.js: email с паролем плюс вход через Google, секрет берём из BETTER_AUTH_SECRET.
  • Добавь плагин organization с командами и ролями и перегенерируй схему через npx @better-auth/cli@latest generate.
  • Почему у меня сессия всегда truthy? Проверь, что код смотрит на session?.user.

Как установить better-auth

1Через Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill better-auth -a claude-code

2Вручную: положить файлы

~/.claude/skills/better-auth/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/better-auth/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о better-auth

Как установить better-auth в Claude Code?

Выполните npx skills add oakoss/agent-skills --skill better-auth -a claude-code. Скилл окажется в ~/.claude/skills/better-auth/SKILL.md и подхватится в следующей сессии.

Что делает этот скилл?

Даёт агенту готовый справочник по better-auth: опции конфига, плагины, стратегии сессий и список антипаттернов. С ним агент не выдумывает API фреймворка, а опирается на эти таблицы.

Что нужно подготовить до настройки аутентификации?

Секрет BETTER_AUTH_SECRET не короче 32 символов, его удобно получить через openssl rand -base64 32, и адрес приложения в BETTER_AUTH_URL. Сам auth.ts держите в ./, ./lib, ./utils или ./src, иначе CLI его не найдёт.

Исходный текст

SKILL.md · MIT
---
name: better-auth
description: |
  Self-hosted TypeScript auth framework with social auth, 2FA, passkeys, organizations, RBAC, and 15+ plugins. Supports Drizzle/Prisma/Kysely adapters. Self-hosted alternative to Clerk/Auth.js.

  Use when: configuring auth, adding plugins, social OAuth, multi-tenant SaaS, organizations with teams and RBAC, two-factor authentication (TOTP/OTP/backup codes), email verification, password reset flows, session management, rate limiting, CSRF and cookie security, Expo/mobile, D1 adapter errors, TanStack Start integration, additionalFields bugs, admin plugin, migrating from NextAuth, migrating from Clerk, migrating from Supabase Auth, or troubleshooting auth issues.
license: MIT
metadata:
  author: oakoss
  version: '1.2'
user-invocable: false
---

# better-auth

**Package**: [email protected] (ESM-only since v1.4.0)
**Docs**: <https://better-auth.com/docs> | **GitHub**: <https://github.com/better-auth/better-auth>

## Environment Setup

| Variable             | Purpose                                                               |
| -------------------- | --------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | Encryption secret (min 32 chars). Generate: `openssl rand -base64 32` |
| `BETTER_AUTH_URL`    | Base URL (e.g., `https://example.com`)                                |

Only define `baseURL`/`secret` in config if env vars are NOT set. CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or `./src`.

## Core Config Options

| Option             | Notes                                         |
| ------------------ | --------------------------------------------- |
| `appName`          | Optional display name                         |
| `baseURL`          | Only if `BETTER_AUTH_URL` not set             |
| `basePath`         | Default `/api/auth`. Set `/` for root.        |
| `secret`           | Only if `BETTER_AUTH_SECRET` not set          |
| `database`         | Required unless using stateless mode (v1.4+)  |
| `secondaryStorage` | Redis/KV for sessions and rate limits         |
| `emailAndPassword` | `{ enabled: true }` to activate               |
| `socialProviders`  | `{ google: { clientId, clientSecret }, ... }` |
| `plugins`          | Array of plugins                              |
| `trustedOrigins`   | CSRF whitelist                                |

## Plugin Reference

| Plugin        | Description                                                                        |
| ------------- | ---------------------------------------------------------------------------------- |
| twoFactor     | TOTP, email OTP, backup codes                                                      |
| organization  | Multi-tenant orgs, teams, invitations, RBAC                                        |
| admin         | User management, impersonation, banning                                            |
| passkey       | WebAuthn passwordless login                                                        |
| magicLink     | Email-based passwordless login                                                     |
| jwt           | JWT tokens with key rotation, JWKS                                                 |
| oauthProvider | Build your own OAuth 2.1 provider (separate `@better-auth/oauth-provider` package) |
| sso           | Enterprise SSO with OIDC, OAuth2, SAML 2.0 (separate `@better-auth/sso` package)   |
| scim          | Enterprise user provisioning (separate `@better-auth/scim` package)                |
| stripe        | Payment and subscription management                                                |
| bearer        | API token auth for mobile/CLI                                                      |
| apiKey        | Token-based auth with rate limits                                                  |
| oneTap        | Google One Tap frictionless sign-in                                                |
| anonymous     | Guest user access without PII                                                      |
| genericOAuth  | Custom OAuth providers with PKCE                                                   |
| emailOTP      | Email-based one-time password auth                                                 |
| phoneNumber   | Phone/SMS-based OTP sign-in                                                        |
| username      | Username-based sign-in (alternative to email)                                      |
| multiSession  | Multiple accounts in same browser                                                  |
| openAPI       | Interactive API docs at `/api/auth/reference`                                      |

## Session Strategies

| Strategy          | Format                  | Use Case          |
| ----------------- | ----------------------- | ----------------- |
| Compact (default) | Base64url + HMAC-SHA256 | Smallest, fastest |
| JWT               | Standard JWT            | Interoperable     |
| JWE               | A256CBC-HS512 encrypted | Most secure       |

## Getting Started

For new projects or first-time Better Auth setup, use the official interactive setup skill:

```bash
npx skills add better-auth/skills -s create-auth-skill
```

This walks through framework detection, database selection, auth method choices, plugin setup, and generates the initial configuration.

## Anti-Patterns

| Anti-Pattern                             | Correct Approach                                                               |
| ---------------------------------------- | ------------------------------------------------------------------------------ |
| Using `d1Adapter`                        | Use Drizzle or Kysely adapter with `provider: "sqlite"`                        |
| Using table name in config               | Use ORM model name, not DB table name                                          |
| Forgetting CLI after plugin changes      | Re-run `npx @better-auth/cli@latest generate`                                  |
| `tanstackStartCookies()` not last plugin | Must be the last plugin in array (TanStack Start)                              |
| Checking `session` for login state       | Check `session?.user` — session object is always truthy                        |
| Missing `nodejs_compat` flag             | Required in `wrangler.toml` for Cloudflare Workers                             |
| Kysely CamelCasePlugin with auth         | Use separate Kysely instance without the plugin                                |
| Using old `reactStartCookies` import     | Renamed to `tanstackStartCookies` from `better-auth/tanstack-start` in v1.4.14 |

## Common Mistakes

| Mistake                                                                | Correct Pattern                                                                                |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Setting `baseURL` and `secret` in config when env vars are already set | Only define these in config if `BETTER_AUTH_URL` and `BETTER_AUTH_SECRET` env vars are NOT set |
| Using CommonJS require syntax with better-auth v1.4+                   | better-auth is ESM-only since v1.4.0; use `import` syntax exclusively                          |
| Not re-running CLI generate after adding or changing plugins           | Always run `npx @better-auth/cli@latest generate` after plugin changes to update DB schema     |
| Checking `session` object truthy state for login detection             | Check `session?.user` instead; the session object itself is always truthy                      |
| Using `d1Adapter` directly for Cloudflare D1                           | Use Drizzle or Kysely adapter with `provider: "sqlite"` for D1 compatibility                   |

## Breaking Changes

| Version | Change                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------ |
| v1.4.14 | `reactStartCookies` renamed to `tanstackStartCookies` (import from `better-auth/tanstack-start`) |
| v1.4.6  | `allowImpersonatingAdmins` defaults to `false`                                                   |
| v1.4.0  | ESM-only (no CommonJS); SSO, SCIM, OAuth Provider moved to separate packages                     |
| v1.3.0  | Multi-team table structure: new `teamMembers` table needed                                       |

## Delegation

When working on auth, delegate to:

- `application-security` — Security architecture and threat modeling
- `database` — Drizzle ORM schema and migrations
- `tanstack-start` — TanStack Start integration patterns

## Resources

- **Docs**: <https://better-auth.com/docs>
- **Options Reference**: <https://better-auth.com/docs/reference/options>
- **LLMs.txt**: <https://better-auth.com/llms.txt>
- **Changelog**: <https://www.better-auth.com/changelogs>
- **TanStack Start**: <https://www.better-auth.com/docs/integrations/tanstack>
- **Expo**: <https://www.better-auth.com/docs/integrations/expo>

## References

- [Database Adapters](references/database-adapters.md) — Drizzle, Kysely, Prisma adapters, Cloudflare Workers factory pattern
- [Session Management](references/sessions.md) — Cookie cache, stateless sessions, storage priority, freshAge constraints
- [Plugins and Social Auth](references/plugins.md) — Plugin setup, OAuth 2.1 provider, admin RBAC, social provider scopes
- [Email and Password](references/email-password.md) — Verification, password reset, timing attack prevention, hashing (scrypt, argon2), token security
- [Two-Factor Authentication](references/two-factor.md) — TOTP, email/SMS OTP, backup codes, trusted devices, 2FA session flow
- [Organizations](references/organizations.md) — Multi-tenant orgs, teams, invitations, RBAC, dynamic access control, lifecycle hooks
- [Configuration](references/configuration.md) — User/account config, rate limiting, hooks, CSRF, trusted origins, cookie/OAuth security, production checklist
- [Framework Integration](references/frameworks.md) — TanStack Start setup, Expo/React Native, client imports, type safety
- [Migration Guides](references/migration-guides.md) — Migrate from NextAuth/Auth.js, Clerk, or Supabase Auth with schema mappings and session strategies
- [Troubleshooting](references/troubleshooting.md) — D1 consistency, CORS, OAuth redirect, admin 403, nanostore refresh, known bugs

© oakoss · MIT · oakoss/agent-skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →

Сначала — better-auth от других авторов.

better-auth mrgoonie Проводит по подключению Better Auth: email-пароли, OAuth, 2FA, passkeys и роли. Встраивает вход и сессии в TypeScript-проект. CX Codex +1 402установок better-auth giuseppe-trisciuoglio Скилл с готовыми шаблонами Better Auth: подключение к NestJS, Drizzle ORM и PostgreSQL, вход через соцсети и плагины вроде 2FA и passkey. CX Codex +1 3 800установок better-auth secondsky Скилл better-auth для Claude Code помогает подключить аутентификацию и разобраться с ошибками адаптера Cloudflare D1. Он также покрывает OAuth, двухфакторную защиту и роли доступа. CX Codex +1 511установок better-auth pproenca Скилл по Better Auth для TypeScript: помогает поднять инстанс, выбрать адаптер, настроить сессии и перейти с другой auth-библиотеки. CX Codex +1 150установок better-auth-plugins bobmatnyc Скилл better-auth-plugins направляет ассистента при настройке двухфакторной аутентификации, passkey, JWT или организаций в Better Auth на TypeScript. Помогает связать клиентские и серверные плагины. CX Codex +1 370установок better-auth-security-best-practices better-auth Скилл better-auth-security-best-practices настраивает защиту Better Auth: ограничивает частоту запросов, проверяет происхождение, шифрует токены и защищает пользовательские сессии. CX Codex +1 52 200установок better-auth-integrations bobmatnyc Скилл better-auth-integrations помогает подключить Better Auth к веб-фреймворкам на TypeScript: Next.js, SvelteKit, Remix, Express и Hono. Настраивает обработчики /api/auth/* и работу с cookies в SSR. CX Codex +1 371установок neon-auth neondatabase Скилл neon-auth для Claude Code настраивает аутентификацию через Neon Auth в новом приложении. Он подключается к задачам входа, регистрации, сброса пароля и OAuth. CX Codex +1 38 600установок safe-action-better-auth next-safe-action Скилл safe-action-better-auth для Claude Code помогает добавить аутентификацию и проверку доступа к safe actions через Better Auth. Он включается при настройке middleware, сессии и отказа в доступе. CX Codex +1 499установок better-auth-scaffold pproenca Скилл better-auth-scaffold раскладывает Better Auth по файлам в проекте Next.js с App Router и Drizzle: шаблоны, три набора плагинов, генерация схемы и миграции. CX Codex +1 143установок

Из того же набора106

Весь набор →
react-native Помогает проектировать мобильные приложения на React Native и Expo с файловой маршрутизацией, EAS Build и нативными API под iOS и Android. CX Codex +1 117установок tiptap Скилл помогает собирать React-редакторы на Tiptap: настраивать расширения, SSR, загрузку изображений и совместное редактирование. Пригодится при добавлении редактора в приложение. CX Codex +1 117установок agent-patterns Скилл agent-patterns для Claude Code описывает паттерны мультиагентных систем и субагентов для организации задач в изолированных контекстах. CX Codex +1 115установок tanstack-cli Скилл tanstack-cli настраивает сборку библиотек через TanStack Config и Vite с генерацией типов и релизом через conventional commits. CX Codex +1 115установок meta-skill-creator Скилл meta-skill-creator помогает создавать и проверять агентские скиллы по открытому стандарту Agent Skills. Он пригодится при подготовке SKILL.md, структуры папок и файлов для распространения. CX Codex +1 114установок figma-developer Скилл figma-developer для Claude Code получает из Figma цвета, шрифты и иконки через REST API и собирает CSS-переменные и React-компоненты. Автоматизирует перенос изменений макета в код. CX Codex +1 114установок tanstack-store Объясняет агенту устройство TanStack Store: стор, производные значения, батчи и эффекты. Описывает общее состояние нескольких компонентов. CX Codex +1 113установок hono Скилл по веб-фреймворку Hono для создания API и edge-функций на Cloudflare Workers, Bun, Deno и Node.js. CX Codex +1 112установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой