技能

什麼是技能

supastack 內建 Agent Skills：當工作匹配時，編碼智慧體會載入這些簡短、面向任務的指令。智慧體不必在每次提示中猜測 kit 的約定，而是對功能、支付、資料庫變更和測試遵循相同的步驟。技能遵循開放的 Agent Skills 格式，因此可在 Claude Code、Cursor、Codex、GitHub Copilot、Gemini CLI 及其他相容智慧體中使用。

技能的位置

技能位於 .agents/skills/，每個技能一個資料夾，內含 SKILL.md。.claude/skills/ 中存放供 Claude Code 使用的相同副本。

哪些智慧體讀取它們

Codex、Cursor、GitHub Copilot、Gemini CLI 和 OpenCode 讀取 .agents/skills/；Claude Code 讀取 .claude/skills/。當請求與技能的描述匹配時，智慧體會自動選用；你也可以點名，比如說“use the database-schema-change skill”。

哪些倉庫包含它們

all-platforms 倉庫包含全部技能。web、mobile 和 desktop 倉庫包含適用於各自平臺的技能；端到端測試和 CI 技能僅隨 all-platforms 倉庫提供。

設定與環境

讓 kit 執行、部署和配置到位的技能。

• 本地環境設定 (local-environment-setup) — 初始化或修復本地環境時使用：首次克隆、.env 缺失或損壞、Postgres、遷移或埠問題。
• 部署與環境變數 (deploy-and-env-vars) — 部署、選擇託管目標，或新增/修改環境變數時使用。
• 新增依賴 (adding-a-dependency) — 新增、升級、移動或移除 npm 依賴，或 CI 的許可證/審計檢查失敗時使用。
• 從上游升級 (upgrading-from-upstream) — 把更新的 supastack 版本引入基於它構建的產品時使用。

構建功能

在各平臺新增產品功能的技能。

• 新增 Web 功能 (add-a-web-feature) — 新增自帶資料、server actions、導航和測試的產品頁面或版塊時使用。
• 新增 API 端點 (add-an-api-endpoint) — 新增或修改公開的 /api/v1 端點、其 OpenAPI 檔案或 API 金鑰許可權範圍時使用。
• 新增 UI 元件 (add-a-ui-component) — 構建遵循 kit 樣式規則的版塊、區塊、表單控制元件或可複用元件時使用。
• 更改主題或樣式 (change-the-theme-or-style) — 改變產品外觀時使用：設計風格、配色包、密度、圓角、字型或佈局。
• 新增營銷頁面或部落格文章 (add-a-marketing-page-or-blog-post) — 新增或編輯公開頁面、定價頁、法律頁面、部落格文章或檔案指南時使用。
• 新增移動端頁面 (add-a-mobile-screen) — 在 Expo 移動應用中新增或修改頁面時使用。
• 新增桌面端能力 (add-a-desktop-capability) — 修改 Tauri 桌面應用時使用：視窗、托盤、全域性快捷鍵或自動更新。
• 新增通知 (add-a-notification) — 新增應用內通知、推送通知或摘要條目時使用。

認證與支付

登入、計費與套餐相關技能。

• 新增認證方式 (add-an-auth-method) — 修改登入方式時使用：社交登入、魔法連結、郵箱驗證碼、passkey 或兩步驗證。
• 新增支付服務商 (add-a-payment-provider) — 啟用計費服務商，或編寫帶 checkout、客戶門戶和 webhook 的新計費介面卡時使用。
• 調整套餐與定價 (change-plans-and-pricing) — 新增、重新命名套餐或調整價格時使用：價格、試用、席位、權益、用量上限或積分。

資料與整合

資料庫模式、AI、任務、郵件、儲存與翻譯的技能。

• 資料庫模式變更 (database-schema-change) — 新增或修改表、列、索引或關係並生成遷移時使用。
• 新增 AI 功能 (add-an-ai-feature) — 新增模型呼叫、聊天或智慧體工具、持久化 AI 任務、預算或自帶金鑰時使用。
• 新增後臺任務 (add-a-background-job) — 新增在請求後、定時或按工作區執行的任務時使用。
• 新增或編輯郵件 (add-or-edit-an-email) — 新增或修改事務性郵件，或更換投遞服務商時使用。
• 使用檔案儲存 (use-file-storage) — 新增頭像、logo、附件等上傳或檔案儲存功能時使用。
• 新增翻譯 (add-translations) — 新增或修改使用者可見文案、翻譯或新增語言時使用。

質量與交付

測試、驗證、評審與 CI 的技能。

• 編寫單元測試 (writing-unit-tests) — 編寫或修復 Vitest 單元測試或整合測試時使用。
• 編寫 E2E 測試 (writing-e2e-tests) — 在本地或 CI 中新增或修復 Playwright 端到端測試時使用。
• 驗證變更 (verify-changes) — 在交接、提交或建立 pull request 前，選擇並執行正確的檢查時使用。
• 除錯失敗的 CI 執行 (debugging-a-failing-ci-run) — GitHub Actions 執行失敗、需要定位並修復原因時使用。
• 評審 PR (reviewing-a-pr) — 評審 pull request 或 diff 的正確性、工作區隔離和約定時使用。

新增自己的技能

新建一個資料夾，資料夾名與 frontmatter 中的 name 一致，並寫好說明何時使用的 name 和 description。同時把它複製到 .claude/skills/，讓所有智慧體都能找到。