Skill
Thêm xác thực TypeScript với ak:better-auth
Lập kế hoạch và triển khai Better Auth trong khi giữ credential, thay đổi schema, session cùng production rollout luôn rõ ràng.
Dùng ak:better-auth để thêm hoặc tinh chỉnh xác thực trong application
TypeScript hay JavaScript. Skill bao quát thiết lập server và client Better
Auth, email/password, social OAuth, session, database adapter cùng plugin tùy
chọn như two-factor authentication, passkey, magic link, username và
organization.
Chọn ak:better-auth cho integration Better Auth
Dùng ak:better-auth khi
- Project dùng TypeScript hoặc JavaScript và đã chọn Better Auth.
- Bạn cần luồng email/password, OAuth, session, account linking, MFA, passkey, magic link, username hoặc organization.
- Bạn cần nối xác thực với database và framework handler hiện có.
- Bạn muốn implementation đúng scope kèm bằng chứng migration và flow verification.
Chọn workflow khác khi
- Bạn vẫn đang so sánh sản phẩm xác thực hoặc xác định threat model. Dùng
ak:brainstormhoặcak:advisetrước khi chọn implementation. - Task là backend tổng quát chưa chọn Better Auth. Dùng
ak:backend-development. - Bạn chỉ cần security review độc lập. Dùng
ak:securityhoặcak:code-reviewtrên implementation hiện có. - Application không tương thích với package Better Auth hoặc adapter đã cài. Giữ nguyên auth stack hiện tại trừ khi migration được duyệt riêng.
Chuẩn bị application và credential
Trước khi bắt đầu:
- Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho runtime cùng scope hiện tại.
- Xác định framework, runtime, package manager, version Better Auth, database, ORM, route layout, cookie policy cùng user schema hiện có từ project.
- Xác định sign-in method được hỗ trợ, session lifetime, quy tắc account linking, email verification, password reset, recovery, role và deletion.
- Dùng development credential cùng database cô lập. Giữ
BETTER_AUTH_SECRET, database URL, OAuth client secret, credential của email provider và production token ngoài prompt, log, code cùng Git. - Ghi rõ có cho phép cài package, sinh schema, chạy migration, gửi email, đổi provider console hay deploy không.
Ví dụ đi kèm bao quát Next.js, Nuxt, SvelteKit, Astro, Hono và Express, cùng kết nối trực tiếp SQLite, PostgreSQL, MySQL, MongoDB, Drizzle, Prisma và Kysely. Hãy coi chúng là pattern, không phải bằng chứng package version hoặc project hiện tại cung cấp cùng API.
| Runtime | Cách gọi | Ranh giới khả dụng |
|---|---|---|
| Claude Code | /ak:better-auth ... | Có thể kiểm tra và sửa project bằng tool khả dụng; Engineer hỗ trợ phân phối native cùng plugin rõ ràng. |
| Cursor | /ak:better-auth ... | Dùng slash syntax đã được người dùng xác minh; parity rộng hơn về Agent, Hook và tool chưa được thiết lập. |
| Codex | $ak:better-auth ... | Dùng native Skill discovery; Hook được chuyển đổi một phần và tool khả dụng tùy session. |
Xem Runtime adapter để hiểu khác biệt theo từng component.
Chạy Skill
Argument shape được khai báo là [auth-method or feature]. Nêu stack hiện có,
flow cho người dùng, security boundary, quyền migration cùng bằng chứng cần có
trong yêu cầu.
/ak:better-auth "Add GitHub OAuth to the existing Next.js app and Better Auth database. Preserve email/password login, request only identity scopes, add callback and account-linking tests, generate but do not apply migrations, and do not use production credentials or deploy."/ak:better-auth "Add GitHub OAuth to the existing Next.js app and Better Auth database. Preserve email/password login, request only identity scopes, add callback and account-linking tests, generate but do not apply migrations, and do not use production credentials or deploy."$ak:better-auth "Add GitHub OAuth to the existing Next.js app and Better Auth database. Preserve email/password login, request only identity scopes, add callback and account-linking tests, generate but do not apply migrations, and do not use production credentials or deploy."Input hữu ích phân biệt configuration với hành động bên ngoài:
| Input | Cần gồm |
|---|---|
| Authentication contract | Sign-up, sign-in, sign-out, verification, reset, recovery, linking, deletion cùng failure state |
| Stack hiện có | Framework handler, version Better Auth, client package, database adapter, schema, mailer cùng test tool |
| Security policy | Session duration, cookie, rate limit, redirect allowlist, OAuth scope, role, audit need cùng cách xử lý secret |
| Ranh giới mutation | Tệp, dependency, generated schema, migration, database write, thay đổi provider console cùng deployment được phép |
| Bằng chứng | Typecheck, test tập trung, migration diff, local flow check, security review cùng production step còn lại |
Quan sát các giai đoạn integration
Bạn nên kiểm tra được các giai đoạn sau:
- Lần chạy lập bản đồ bề mặt xác thực hiện tại. Skill tìm framework handler, server/client configuration, schema, cách dùng session, protected route, environment contract cùng test thực tế.
- Lần chạy xác nhận flow và threat boundary. Redirect, account linking, verification, recovery, session revocation, authorization cùng abuse handling được xác định trước khi sửa code.
- Lần chạy chọn Better Auth API tương thích. Built-in method và plugin được kiểm tra với version đã cài; thêm plugin cũng kích hoạt review ảnh hưởng schema.
- Lần chạy triển khai slice nhỏ nhất đã duyệt. Server configuration, route handler, client call, UI state cùng error behavior bám pattern hiện có của project.
- Lần chạy chuẩn bị thay đổi database an toàn. Generated schema hoặc migration được review như artifact. Áp dụng chúng vào bất kỳ database nào là một ranh giới mutation riêng.
- Lần chạy xác minh và báo cáo. Skill ghi lại test tập trung, kết quả typecheck hoặc build, flow coverage, tệp đổi, ảnh hưởng schema cùng bước provider hay deployment chưa làm.
Giữ secret, migration và live flow dưới quyền duyệt
Thiết lập xác thực có thể thay đổi identity data
Schema migration, verification email, OAuth callback, account linking, session revocation cùng deletion flow có thể thay đổi persistent hoặc external state. Dùng account và database cô lập cho đến khi bạn duyệt rõ một thao tác production.
- Cài package có thể chạy lifecycle script và sửa lockfile.
npx @better-auth/cli generatetạo schema artifact; lệnh migration có thể đổi table cùng data. Review output được sinh trước khi áp dụng.- Công việc trên provider dashboard có thể tạo credential và đổi redirect URL. Cấp quyền đó riêng và chỉ yêu cầu scope cần thiết.
- Initializer tùy chọn đi kèm là ví dụ interactive. Nó có thể ghi tệp
auth.ts, in environment content được sinh ra terminal và thay.envhiện có sau khi đổi tên tệp đó thành.env.backup. Kiểm tra diff và bảo vệ secret file hiện có trước khi dùng. - Test email, SMS, OAuth, passkey cùng external rate limit có thể liên hệ service thật hoặc người dùng thật. Ưu tiên fake, local mail capture và test tenant.
- Commit, push, publication cùng deployment vẫn cần phê duyệt riêng.
Xác minh kết quả
Kết quả hoàn tất nên cung cấp:
- Flow matrix đã triển khai, gồm success, invalid input, expired token, unverified account, duplicate account cùng signed-out behavior khi liên quan.
- Chính xác tệp đổi, package, tên environment variable, generated schema cùng migration artifact chưa áp dụng mà không làm lộ value.
- Lệnh test server, client, callback, session, authorization cùng rate limit tập trung và kết quả.
- Bằng chứng redirect bị giới hạn, secret chỉ ở server, cookie cùng session behavior khớp policy và OAuth scope là tối thiểu.
- Production checklist cho provider URL, secret injection, email delivery, database backup/migration, monitoring, rollback cùng phê duyệt deployment.
Xử lý sự cố hoặc tiếp tục
| Triệu chứng | Bước tiếp theo an toàn |
|---|---|
| Ví dụ framework không compile | Đọc version Better Auth cùng framework đã cài, rồi điều chỉnh pattern handler hiện có của project thay vì sao chép reference nguyên văn. |
| Schema generation đổi table ngoài dự kiến | Dừng trước migration, so generated schema với plugin đã bật cùng database hiện tại, rồi thu hẹp hoặc lập kế hoạch lại. |
| OAuth báo redirect mismatch | So khớp chính xác local callback URL, deployed origin, provider configuration, proxy header cùng base URL theo môi trường mà không làm lộ credential. |
| Test email, magic link hoặc reset gửi message thật | Dừng sender, chuyển sang fake hoặc test mailbox, rotate token bị lộ nếu cần rồi chạy lại với recipient cô lập. |
| Session hoặc account linking hoạt động ngoài dự kiến | Giữ bằng chứng, kiểm tra cookie origin/domain, trusted redirect, provider identity mapping cùng account row trong database trước khi đổi policy. |
| Runtime không nhận diện Skill | Xác nhận target cùng scope, mở session mới, rồi làm theo Runtime không tìm thấy Skill hoặc Agent. |
Tiếp tục với ak:databases cho schema review có scope riêng, ak:security cho
security audit hoặc Tổng quan Engineer Kit cho implementation
được điều phối.
Biết các giới hạn hiện tại
- Skill là guidance cùng implementation context, không phải identity provider, secrets manager, email/SMS service, database backup system hay penetration test.
- Better Auth cùng provider API thay đổi theo thời gian. Xác nhận package docs, adapter support, plugin requirement, callback format cùng security notice hiện tại trước khi dựa vào ví dụ đi kèm.
- Source không chứng minh tương thích với mọi framework version, deployment host, proxy, browser, passkey device, mail provider hay database topology.
- Test đi kèm kiểm tra initializer, không phải toàn bộ authentication, authorization, recovery, migration hay production rollout của application.
- Stable và beta chứa nội dung Skill cùng resource giống nhau trong cặp release này. Diagnostic Codex Hook của beta không thay đổi workflow này.
Lập kế hoạch và vận hành hạ tầng với ak:devops
Chuẩn bị và xác minh công việc Cloudflare, Docker, Google Cloud, Kubernetes, CI/CD và GitOps với cổng phê duyệt rõ ràng cho triển khai và xóa tài nguyên.
Tích hợp thanh toán an toàn với ak:payment-integration
Triển khai checkout và webhook SePay, Polar hoặc Stripe với credential, idempotency, financial side effect cùng bằng chứng go-live rõ ràng.