better-auth-best-practices

better-auth-best-practices skill 概覽

better-auth-best-practices skill 是一份實用的 Better Auth 導入設定指南，特別適合那些不只想用一句泛泛的「幫我加上 auth」提示就草草帶過的情境。對於在 TypeScript 應用中使用 Better Auth、並需要處理初始設定、auth.ts 擺放位置、環境變數、資料庫 adapter、路由串接、migration、session 與 plugin 感知設定的開發者來說，這個 skill 特別有價值。

這個 skill 實際上是拿來做什麼的

當你的目標是讓 Better Auth 整合更順利落地、減少那些本來可以避免的錯誤時，就該用 better-auth-best-practices。它最擅長的地方，是把像「幫我在 app 裡設好 Better Auth」這種模糊需求，轉成更完整的實作規劃：包含正確的安裝步驟、檔案位置預期，以及驗證檢查點。

最適合的使用者

這個 skill 很適合：

• 正在替新專案或既有專案加入 Better Auth 的開發者
• 要協助處理 auth.ts、adapters、sessions、plugins 或 env 設定的 agents
• 想先有一個更穩妥起點，再去對照官方範例的團隊

如果你已經知道自己使用的 framework 與資料庫，但需要一條可靠的 Better Auth 設定路徑，這個 skill 會特別實用。

它和一般 prompt 有什麼不同

一般 prompt 可能會產出看似合理的 auth 程式碼，但漏掉 Better Auth 特有的細節。better-auth-best-practices skill 則補上來自 repo 的實務指引，包括：

• 必要的 env 變數，例如 BETTER_AUTH_SECRET 與 BETTER_AUTH_URL
• CLI 會在哪裡尋找 auth.ts
• 什麼時候該執行 migration 或 schema generation 指令
• plugin 有變動後需要重新跑 CLI 步驟
• 安裝後可用 GET /api/auth/ok 做簡單健康檢查

因此，比起籠統的「做一個登入功能」請求，它在安裝決策與排錯上更有幫助。

它不能取代什麼

這個 skill 不能取代即時更新的 Better Auth 官方文件。repo 已明確引導使用者前往 https://better-auth.com/docs 查看最新程式範例與 API 變更。比較好的用法是：把這個 skill 當成加速設定與協助判斷的工具，再回頭用官方文件確認 framework 專屬程式碼。

核心採用判斷

如果你想要的是帶有實際操作細節的 Better Auth 專屬設定指引，就值得安裝 better-auth-best-practices。如果你需要的是完整 framework starter、production 安全審查，或是超出 Better Auth 初始整合範圍的進階授權架構，那就不該把它當成主要方案。

如何使用 better-auth-best-practices skill

安裝 better-auth-best-practices skill

使用以下指令安裝：

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

這會從 better-auth/skills repository 加入 better-auth-best-practices 的指引內容。

先讀對的來源檔

這個 skill 內容很精簡。建議先看：

• better-auth/best-practices/SKILL.md

這個 skill 資料夾裡沒有額外的 references/、rules/ 或輔助 script，所以幾乎所有可用指引都集中在這一個檔案。

先準備它預設需要的最小安裝脈絡

在呼叫這個 skill 之前，先整理好以下資訊：

• framework 或 runtime
• 資料庫選擇與 adapter
• 你要用 email/password、OAuth，或兩者都要
• auth handlers 預期使用的 route path
• 是否需要 plugins
• auth.ts 在 repo 裡應該放哪裡

少了這些前提，輸出通常會停留在過度泛化的層次。

從 Better Auth 內建工作流程開始

repo 提供了一個直接明確的順序：

1. npm install better-auth
2. 設定 BETTER_AUTH_SECRET 與 BETTER_AUTH_URL
3. 建立包含資料庫與設定的 auth.ts
4. 建立 framework 的 route handler
5. 執行 npx @better-auth/cli@latest migrate
6. 用 GET /api/auth/ok 驗證

如果你的 prompt 沒有把這些檢查點涵蓋進去，建議直接要求模型依照這個順序組織答案。

依你的設定使用正確的 CLI 指令

這個 skill 特別指出一個很重要的差異：

• 內建 adapter 流程使用 npx @better-auth/cli@latest migrate
• Prisma 或 Drizzle 的 schema 產生流程使用 npx @better-auth/cli@latest generate

這點很關鍵，因為「跑 Better Auth CLI」這種說法太模糊。如果你用的是 Prisma 或 Drizzle，請在 prompt 裡明確寫出來，這樣輸出才會用 generate，而不是預設成 migrate。

明確說清楚 auth.ts 檔案位置

Better Auth CLI 會在以下位置尋找 auth.ts：

• ./
• ./lib
• ./utils
• ./src 底下的路徑

如果你的專案放在自訂位置，記得告訴 agent 使用 --config。這是最常見的導入卡點之一，因為程式碼即使看起來正確，CLI 還是可能找不到設定檔。

在 prompt 中一併交代環境變數決策

這個 skill 特別點出兩個關鍵變數：

• BETTER_AUTH_SECRET
• BETTER_AUTH_URL

它也提到，只有在這些 env 變數沒有設定時，你才應該在 config 裡定義 baseURL 或 secret。這個細節能避免重複或互相衝突的設定。若想拿到更高品質的輸出，建議一併說明：

• local 與 production 的 base URL
• secret 的管理方式
• 是否使用 .env.local、平台 secrets 或 Docker envs

把粗略需求改寫成更強的 better-auth-best-practices prompt

較弱的 prompt：

• 「幫我的 app 設定 Better Auth」

較強的 prompt：

• 「Use the better-auth-best-practices skill to set up Better Auth in a Next.js TypeScript app with PostgreSQL and Drizzle. Put auth.ts under src/lib. We need email/password now and Google OAuth later. Show required env vars, route handler placement, whether to run generate or migrate, and how to verify setup with /api/auth/ok.」

這樣寫有效的原因：

• framework 很明確
• adapter 路徑很明確
• 檔案位置很明確
• auth 方法很明確
• CLI 選擇不再模糊
• 驗證步驟也包含進來了

要求輸出依實作順序排列

想把 better-auth-best-practices 用得更好，建議要求答案依照這個格式輸出：

1. 要安裝的 packages
2. env 變數
3. auth.ts
4. route handler
5. migration 或 schema 指令
6. plugin additions
7. 驗證步驟
8. 可能的失敗點

這個結構最符合 skill 的強項，也能減少來回追問。

使用具 plugin 感知的 prompts

這個 skill 明確提醒：新增或變更 plugins 後，必須重新執行 CLI。如果你的設定依賴 plugins，請一開始就在 prompt 裡說清楚。否則模型可能只產出可用的核心 config，卻漏掉 plugins 帶來的 schema 或 migration 更新。

先驗證整合成功，再擴大範圍

不要一安裝完就直接跳去做完整 UI flow。先確認：

• env 變數有正確載入
• auth.ts 可以被找到
• CLI 已成功完成
• GET /api/auth/ok 會回傳 { status: "ok" }

這個實務檢查點，對提升安裝成功率最有幫助。

better-auth-best-practices for Access Control 的最佳工作流程

如果你要用 better-auth-best-practices for Access Control，先拿這個 skill 把 authentication 基礎打好，再往上疊 authorization 需求。比較好的 prompt 會像這樣：

• 「先設定 Better Auth，再說明 role 或 permission checks 應該掛在哪些 route handlers、session handling 或 plugin config 上。把 Better Auth config 負責的部分，和 app 層級 access control 必須自行實作的部分分開說明。」

這樣可以避免模型過度暗示「只要設好 Better Auth，就等於授權邏輯也都解決了」。

better-auth-best-practices skill 常見問題

這個 skill 適合第一次安裝 Better Auth 嗎？

適合。這個 skill 在第一次安裝時最有價值，因為它涵蓋了人們最常漏掉的重複性設定決策：env 變數、檔案位置、CLI 用法，以及驗證方式。當你的整合已經很穩定、只差查一個很小的 API 細節時，它的價值就相對沒那麼高。

沒看文件，只靠 better-auth-best-practices 夠嗎？

不夠。repo 本身就寫明應該查閱 better-auth.com/docs 來取得最新範例與 API 細節。正確做法是用這個 skill 提升設定品質、降低猜測成本，再回頭用文件確認精確實作。

什麼情況下它會比一般 AI prompt 更好？

當任務明確屬於 Better Auth，而且對安裝細節很敏感時，它就會更好。一般 prompt 很可能略過：

• BETTER_AUTH_SECRET 的長度預期
• BETTER_AUTH_URL
• auth.ts 的搜尋路徑
• generate 與 migrate 的差異
• plugin 變更後要重新執行 CLI 步驟

better-auth-best-practices 指南是 framework 專用的嗎？

不完全是。它提供的是可攜式的 Better Auth 工作流程，但 framework 專屬的 route 與 handler 程式碼，仍然要靠官方文件或你的 app 脈絡來補齊。如果你沒有明確說出 framework，拿到的建議就會比較寬泛。

新手也能用 better-auth-best-practices skill 嗎？

可以，但新手通常需要提供比自己想像中更多的脈絡。至少要包含 framework、資料庫與想要的登入方式。否則輸出可能技術上沒錯，卻不能直接執行。

它能把 Access Control 從頭到尾都處理好嗎？

不能單靠它完成。better-auth-best-practices for Access Control 很適合幫你建立 auth 設定基礎，並指出授權議題應該在哪些地方接上，但你仍然需要自行定義應用層級的 permission rules、受保護 routes，以及實際 enforcement strategy。

什麼時候不該使用這個 skill？

以下情況建議跳過：

• 你不是在用 Better Auth
• 你只需要文件中的某一個精確 API 範例
• 你需要完整的 production 安全稽核
• 你的主要問題是 app 的 authorization 設計，而不是 Better Auth 安裝

如何改善 better-auth-best-practices skill 的使用效果

提供具體專案資訊給這個 skill

想更快提升輸出品質，最有效的方法是直接提供：

• framework
• runtime
• database 與 ORM
• auth.ts 位置
• login methods
• plugin 清單
• deployment environment

當這些細節清楚時，better-auth-best-practices skill 會變得更可執行。

一開始就要求它處理可能的失敗點

一個好的 prompt 可以直接加上：

• 「列出這個 stack 最常見的設定錯誤」
• 「告訴我 CLI 會不會找不到 auth.ts」
• 「說明我該用 generate 還是 migrate，以及原因」
• 「示範 env 變數如何覆蓋 config 值」

這類問題比單純要求產生程式碼，更能拿到實用的安裝指引。

要求驗證內容，而不只是程式碼

很多品質不佳的 auth 輸出看起來很完整，但其實沒有驗證過。請要求模型一併包含：

• GET /api/auth/ok 的預期結果
• CLI 指令成功後應該看到什麼
• route 失敗時該檢查哪些地方
• 加入 plugins 後哪些項目需要重新檢查

比起一味要求更長的程式碼範例，這樣更能提升第一次就做對的機率。

改善 better-auth-best-practices for Access Control prompts 的寫法

如果你的目標也包含 authorization，請在需求中把關注點拆開：

• 「Part 1: Better Auth installation」
• 「Part 2: session shape and claims」
• 「Part 3: app-level route protection and permission checks」

這樣可以避免答案把設定步驟和業務專屬的 access logic 混在一起。

在第一輪答案後繼續迭代

第一版拿到後，可以用更具體的追問去收斂，例如：

• 「改寫成 Prisma，而不是 built-in adapter」
• 「把 auth.ts 移到 src/utils」
• 「加入 plugin 變更，並告訴我哪個 CLI 指令要重跑」
• 「改成適合 production env handling 的版本」

這個 skill 對具體調整反應最好，不太適合只丟一句很抽象的「幫我再改好一點」。

留意主要失敗模式

最常見的弱輸出通常是：

• 漏掉 env 變數
• 對檔案路徑做了錯誤假設
• 針對 adapter stack 給了錯的 CLI 指令
• 沒提到 plugin 變更後要重新執行 CLI
• 設定完成後沒有驗證步驟

如果缺少上述任一項，建議先要求對方修正，再進入實作。

把這個 skill 當成設定視角，不要當成最終權威

想真正發揮 better-auth-best-practices skill 的價值，最好的方式是先用它整理出乾淨、可執行的安裝方案，再到 https://better-auth.com/docs 核對精確語法與 framework 專屬程式碼。這種搭配，才是把 skill 轉成可運作整合方案的最穩妥做法。