better-auth · oakoss — скилл для Claude Code: что делает и как установить
Скилл для Claude Code подгружает агенту справочник по better-auth: конфиг, плагины, стратегии сессий и типовые ошибки. Даёт справку при настройке входа, 2FA и организаций.
MIT 114 установок ★ 29 обновлён 2026-08-17
npx skills add oakoss/agent-skills --skill better-auth -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/better-auth/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/better-auth/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill better-auth -a codex2Вручную: положить файлы
.agents/skills/better-auth/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill better-auth -a cursor2Вручную: положить файлы
.cursor/skills/better-auth/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/better-auth2Вручную: положить файлы
.github/skills/better-auth/SKILL.md1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill better-auth -a gemini-cli2Командой платформы
gemini skills install https://github.com/oakoss/agent-skills --path skills/better-authВручную: положить файлы
.devin/skills/better-auth/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill better-auth -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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 от других авторов.