email-and-password-best-practices

email-and-password-best-practices 技能總覽

email-and-password-best-practices 是一份聚焦於 Better Auth 的設定指南，適合要實作傳統帳號密碼登入的團隊，補上實務上最常被漏掉的安全環節：電子郵件驗證、密碼重設、密碼規則，以及密碼雜湊設定。它最適合已經確定要用 Better Auth、需要一條快速且正確的路徑，把 email/password 流程做到可上線等級的開發者；而不是只想看一份泛用的 auth 入門說明。

這個技能能幫你完成什麼

如果你真正要做的是把一套可安全上線的完整 email/password 流程接好，就適合用這個技能：

• 啟用 Better Auth 的 email/password 登入
• 寄送驗證信
• 在需要時，要求使用者完成驗證後才能登入
• 加上密碼重設信件寄送
• 套用密碼規則與驗證邏輯
• 調整雜湊行為
• 執行必要的 migration 步驟

哪些人適合安裝這個技能

這個技能特別適合：

• 在 Better Auth 專案中加入 username/email 登入的應用團隊
• 想把臨時拼湊的 auth 提示流程，改成可重複套用設定路徑的開發者
• 使用 AI 輔助開發，希望 agent 能記住 Better Auth 專用設定名稱與實作順序的工作流程

如果你還在比較不同 auth provider，或你的應用只使用 OAuth/passkeys、根本不需要密碼，那這個技能的幫助就相對有限。

為什麼它比泛用 auth prompt 更好用

一般 prompt 可能只會叫 agent「加上登入和重設密碼」。但這個技能會把需求收斂成 Better Auth 真正需要動到的設定與順序，例如 emailAndPassword: { enabled: true }、emailVerification.sendVerificationEmail、reset-password 的處理方式，以及 npx @better-auth/cli@latest migrate。這讓 email-and-password-best-practices for Access Control 這種使用情境更可靠，也更不容易漏步驟。

採用前最重要的判斷點

安裝前，請先確認這幾個決策點：

• 你必須已經有，或至少規劃好，要怎麼寄送 email
• 你需要先決定登入前是否必須完成 email 驗證
• 你應該清楚自己的密碼政策期待
• 你需要有權限執行 Better Auth migrations
• 你要能修改 auth server 設定，而不只是調整前端表單

如何使用 email-and-password-best-practices 技能

email-and-password-best-practices 技能的安裝情境

從 Better Auth skills repository 安裝這個技能：

npx skills add https://github.com/better-auth/skills --skill emailAndPassword

之後在 AI coding session 中呼叫它，用來設定、稽核或優化 Better Auth 的帳密流程。

先讀這個檔案

請先從這裡開始：

• better-auth/emailAndPassword/SKILL.md

這段 repository 內容本身很精簡，所以價值主要不在於瀏覽大量輔助檔案，而在於能不能把裡面的指引正確套到你的程式碼庫。

這個技能需要你提供哪些輸入

請把 repository 無法自行推斷的關鍵背景交給 agent：

• 你的 Better Auth config 檔案路徑
• email/password 是否已經部分啟用
• 你使用的 email 發送 provider 或 helper function
• email 驗證是可選還是強制
• 你想要的 reset-password UX
• 任何密碼長度或複雜度要求
• 是否需要自訂 hashing 設定

如果少了這些上下文，agent 還是可以幫你搭出基本骨架，但輸出通常會偏泛用。

把模糊需求改寫成有效 prompt

弱 prompt：

• 「Set up auth with Better Auth.」

更好的 prompt：

• 「Use the email-and-password-best-practices skill to configure Better Auth email/password login in src/lib/auth.ts, require email verification before sign-in, add sendVerificationEmail using our existing sendEmail() helper, implement reset-password email sending, and tell me what migration command and test steps I need.」

這種寫法更有效，因為它直接提供了檔案位置、想要的驗證策略、現有寄信工具，以及預期交付內容。

建議的設定工作流程

實務上建議照這個順序進行：

1. 在 Better Auth 中啟用 email/password。
2. 加上驗證信寄送。
3. 決定登入前是否必須完成驗證。
4. 加上 reset-password 信件寄送。
5. 套用密碼驗證規則。
6. 只有在確實有需求時，才檢查是否要自訂 hashing 設定。
7. 執行 migration。
8. 端對端測試 sign-up、verification、sign-in 與 reset 流程。

這個順序能減少重工，也符合大多數團隊排查 auth 上線問題的方式。

這個技能圍繞的核心設定

這個技能的重點集中在幾個 Better Auth 功能：

• emailAndPassword: { enabled: true }
• emailVerification.sendVerificationEmail
• emailAndPassword.requireEmailVerification
• sendResetPassword
• password policy 設定
• hashing algorithm 自訂
• npx @better-auth/cli@latest migrate

如果你的 prompt 沒有說清楚需要哪些項目，agent 很可能會替你套用你其實不想要的預設值。

電子郵件驗證通常是採用上的主要卡點

對多數團隊來說，最難的不是打開密碼登入，而是把驗證信流程安全地上線。這個技能的價值在於，它會提醒 agent：sendVerificationEmail 會收到 { user, url, token }，而且提供的 url 已經包含驗證連結。這能避免在已經有完整 URL 的情況下，又自己重組連結而出錯。

什麼情況下應該要求完成驗證才能登入

如果你的 access control 模型，是建立在「使用者先確認身分再開始使用帳號」，就應該使用 emailAndPassword.requireEmailVerification。repository 指引也特別提到一個很重要的行為：未驗證的使用者在嘗試登入時，會再次收到新的驗證信。這種實作細節，很多泛用 prompt 往往不會提到。

password reset 的使用建議

如果你的應用支援忘記密碼找回，請明確要求 agent 接好 sendResetPassword，並把完整使用者旅程一起做出來：

• 申請重設
• 收到 email
• 點開連結
• 設定新密碼
• 再次登入

不要只要求「reset password backend」，不然最後很可能只做出半套，少了最關鍵的寄送步驟。

密碼政策與前端驗證

這個技能涵蓋 password policy，但如果你能先講清楚以下幾點，輸出品質會更好：

• 最短長度
• 是否要求特殊字元
• 前端驗證是否要與後端規則一致
• 是否要回傳對使用者友善的驗證訊息

這點尤其重要，因為很多團隊會希望 sign-up、密碼變更與 reset 流程的行為保持一致。

不一定需要自訂 hashing

email-and-password-best-practices 使用流程 包含 hashing customization，但這應該視為進階需求。若你沒有法規遵循、遷移相容性或效能方面的明確理由，建議要求 agent 保留安全預設值，並說明原因，而不是沒必要地更換演算法。

實作後的實務測試清單

請要求 agent 驗證以下情境：

• 新使用者 sign-up 成功
• 驗證信有正常寄出
• 驗證連結可正常使用
• 若有要求驗證，未驗證使用者無法登入
• 在預期情況下，重複嘗試 sign-in 會再次觸發驗證信
• reset-password email 可成功寄送
• 重設後舊密碼失效
• 弱密碼輸入時，驗證錯誤訊息清楚可辨

這也是 email-and-password-best-practices 指南 比單純快速翻 repo 更有價值的地方：它不只幫你貼設定，還會幫你驗證實際行為。

email-and-password-best-practices 技能常見問題

這個技能只適用於 Better Auth 嗎？

是。這是一個針對 Better Auth 設定與流程的 provider-specific 技能。如果你不是使用 Better Auth，這些設定名稱與 migration 步驟都不能直接照搬。

email-and-password-best-practices 技能對新手友善嗎？

大致上算友善，前提是你已經知道 auth config 在哪裡，也知道你的應用怎麼寄 email。若是完全新手，可能還是需要另外補 SMTP、transactional email provider、路由串接，以及前端表單相關知識。

它會自己安裝任何東西嗎？

不會。這個技能是提供給 AI workflow 的操作指引。你的專案仍然需要先完成 Better Auth 基本設定、接好你依賴的 email provider 整合，並且在你的環境中實際執行 migration command。

什麼情況下不該用這個技能？

以下情況建議跳過：

• 你只需要 OAuth 或 passkeys
• 你還在比較 auth 平台，而不是實作 Better Auth
• 你的應用完全禁止密碼登入
• 你要的是整體安全架構檢視，而不是 Better Auth config 任務

這和直接問 LLM 要 auth 建議有什麼不同？

email-and-password-best-practices 技能更聚焦，也更能直接落地。它會把模型引導到 Better Auth 真正的設定面與 verification / reset 流程的操作細節，能有效降低 API 幻覺與漏步驟的機率。

它對 email-and-password-best-practices for Access Control 有幫助嗎？

有，尤其是在你的 access control 依賴「先驗證身分、再授予應用存取權」的情況下更有用。是否要阻擋未驗證使用者登入，是這個技能最能幫你正確落地的重要策略決策之一。

如何提升 email-and-password-best-practices 技能的效果

直接提供正確的 auth 檔案與 mail helper

想最快提升輸出品質，最有效的方法就是直接把正確檔案與既有 email utility 指給 agent。例子如下：

• 「Edit src/lib/auth.ts and use lib/email/sendEmail.ts.」

這能減少猜測，也能避免 agent 自行捏造抽象層。

一開始就講清楚你的驗證政策

在 email-and-password-best-practices 工作中，少一句話，往往就會多出一堆來回修正：

• 「Users must verify email before first sign-in.」

或

• 「Users can sign in before verification, but we still send verification email.」

如果你沒有先說清楚，做出來的實作可能很安全，但就是不符合你的產品需求。

不要只要 config，要要求端到端流程輸出

更強的請求方式是：

• 「Configure the backend and show the frontend/user flow, email triggers, migration command, and manual test plan.」

這樣可以避免只把 auth server 設好，卻沒有人知道使用者實際要怎麼走完整流程的不完整輸出。

留意常見失敗模式

使用這個技能時，常見問題包括：

• 忘了實作真正的 email delivery
• 明明 url 已經提供，卻還自己產生自訂 verification link
• 啟用了 verification，卻沒有決定是否要阻擋 sign-in
• 接好了 reset-password transport，卻沒測 callback path
• 前端加了密碼規則，但和後端驗證不一致

提供明確政策細節，讓密碼處理更扎實

如果你的環境很重視密碼強度，請直接寫出具體要求。「Use strong passwords」太模糊了。更好的 prompt 會明確提到長度、禁止模式、reset 規則，以及既有使用者是要立即符合，還是只在變更／重設時才套用。

請 agent 解釋取捨，而不是只改程式碼

可以加上這句：

• 「Explain why you kept defaults or changed hashing settings, and note any security/usability tradeoffs.」

這能讓輸出更容易審查，也能幫團隊避免流於形式的安全調整。

第一版完成後，用失敗案例做第二輪迭代

agent 產出初版實作後，可以再要求它補強：

• 「Now review this for unverified-user edge cases.」
• 「Add manual test cases for expired reset links.」
• 「Check whether password validation is consistent between sign-up and reset.」

很多時候，email-and-password-best-practices 安裝 的價值，就是在這第二輪才真正體現出來：它能讓迭代始終貼近 Better Auth 的實際行為，而不是滑回泛用的 auth 建議。