Geruyang/agent-skills-library

導出副本邊界與技能別名

遷移、安裝、修復和經驗回寫只作用於當前載入的目標宿主技能副本。原 Codex 技能/MCP、下載的源碼和 original-skills 均為來源材料，不因執行本副本而寫入；只有用戶另行明確要求配置 Codex 產品本身時，才按該產品流程處理指定目標。腳本需要安裝目錄或狀態目錄時，顯式提供目標路徑；不得從 CODEX_HOME 隱式推斷寫入位置。

跨技能名稱可能沿用源庫別名。先查 技能別名表，優先選擇同來源、同插件的條目，再使用其 id 調用或讀取對應入口；不得假定舊 $skill、superpowers:skill 名稱在新宿主直接註冊。不能確定目標時先核對，不替換真實產品命令或 Shell 環境變量。

跨宿主使用約定

本副本供支援 Agent Skills 的客戶端使用。先檢查當前宿主實際提供的工具、權限和已連接服務，再執行正文工作流。原文中的宿主工具標識是能力參考；只有實際發現該工具時才可調用，其他宿主應使用經核驗的等價 MCP、CLI 或 API。沒有等價能力的步驟必須報告不可用，不能虛構調用或完成狀態。

技能資源以本技能目錄為基準；輸出寫入當前項目中用戶指定的位置。通過技能名稱或自然語言觸發，具體快捷命令由宿主決定。涉及真實產品、模型 API、協議字段和官方網址的名稱保持原意。授權、審批、隱私和工具範圍限制在遷移後仍然有效；不得為兼容而擴大權限。具體依賴與遷移說明見同目錄 PORTABILITY.md。

shadcn/ui

用於構建 UI、元件和設計系統的框架。元件通過 CLI 作為源碼添加到用戶的專案中。

重要提示： 使用專案的套件管理器運行所有 CLI 命令：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest — 基於專案的 packageManager。以下範例使用 npx shadcn@latest，但請替換為專案的正確運行器。

當前專案上下文

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

上述 JSON 包含專案配置和已安裝的元件。使用 npx shadcn@latest docs <component> 獲取任何元件的文件和範例 URL。

原則

1. 優先使用現有元件。 在編寫自訂 UI 之前，使用 npx shadcn@latest search 檢查註冊表。同時也檢查社群註冊表。
2. 組合，而非重新發明。 設定頁面 = Tabs + Card + 表單控制項。儀表板 = Sidebar + Card + Chart + Table。
3. 在自訂樣式之前使用內建變體。 例如 variant="outline"、size="sm" 等。
4. 使用語意化色彩。 例如 bg-primary、text-muted-foreground — 絕不使用像 bg-blue-500 這樣的原始值。

關鍵規則

這些規則始終強制執行。每個規則都連結到一個包含錯誤/正確程式碼配對的檔案。

樣式與 Tailwind → styling.md

• className 用於佈局，而非樣式。 絕不覆蓋元件的顏色或排版。
• 不要使用 space-x-* 或 space-y-*。 使用 flex 搭配 gap-*。對於垂直堆疊，使用 flex flex-col gap-*。
• 當寬度和高度相等時使用 size-*。 使用 size-10 而非 w-10 h-10。
• 使用 truncate 簡寫。 而非 overflow-hidden text-ellipsis whitespace-nowrap。
• 不要手動覆蓋 dark: 顏色。 使用語意化令牌（例如 bg-background、text-muted-foreground）。
• 使用 cn() 處理條件類別。 不要編寫手動的模板字面量三元運算式。
• 不要在覆蓋元件上手動設定 z-index。 Dialog、Sheet、Popover 等會自行處理層疊。

表單與輸入 → forms.md

• 表單使用 FieldGroup + Field。 絕不要使用原始的 div 搭配 space-y-* 或 grid gap-* 進行表單佈局。
• InputGroup 使用 InputGroupInput/InputGroupTextarea。 絕不要在 InputGroup 內部使用原始的 Input/Textarea。
• 輸入內部的按鈕使用 InputGroup + InputGroupAddon。
• 選項集（2–7 個選項）使用 ToggleGroup。 不要迴圈 Button 並手動管理 active 狀態。
• 對於分組的複選框/單選按鈕，使用 FieldSet + FieldLegend。 不要使用帶有標題的 div。
• 欄位驗證使用 data-invalid + aria-invalid。 Field 上使用 data-invalid，控制項上使用 aria-invalid。對於 disabled 狀態：Field 上使用 data-disabled，控制項上使用 disabled。

元件結構 → composition.md

• 項目始終位於其組內。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• 對於自訂觸發器，使用 asChild (radix) 或 render (base)。 從 npx shadcn@latest info 檢查 base 欄位。→ base-vs-radix.md
• Dialog、Sheet 和 Drawer 始終需要一個 Title。 為確保無障礙性，必須使用 DialogTitle、SheetTitle、DrawerTitle。如果視覺上隱藏，使用 className="sr-only"。
• 使用完整的 Card 組合。 包含 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要將所有內容都塞進 CardContent。
• Button 沒有 isPending/isLoading。 使用 Spinner + data-icon + disabled 進行組合。
• TabsTrigger 必須位於 TabsList 內部。 絕不要在 Tabs 中直接渲染觸發器。
• Avatar 始終需要 AvatarFallback。 用於圖片載入失敗的情況。

使用元件，而非自訂標記 → composition.md

• 在自訂標記之前優先使用現有元件。 在編寫帶樣式的 div 之前，檢查元件是否存在。
• 提示框使用 Alert。 不要構建自訂的帶樣式 div。
• 空狀態使用 Empty。 不要構建自訂的空狀態標記。
• Toast 通過 sonner。 使用來自 sonner 的 toast()。
• 使用 Separator 替代 <hr> 或 <div className="border-t">。
• 使用 Skeleton 作為載入佔位符。不要使用自訂的 animate-pulse div。
• 使用 Badge 替代自訂的帶樣式 span。

圖標 → icons.md

• Button 中的圖標使用 data-icon。 在圖標上使用 data-icon="inline-start" 或 data-icon="inline-end"。
• 元件內部的圖標不要使用尺寸類別。 元件通過 CSS 處理圖標大小。不要使用 size-4 或 w-4 h-4。
• 將圖標作為物件傳遞，而非字串鍵。 使用 icon={CheckIcon}，而非字串查找。

CLI

• 不要手動解碼或獲取預設程式碼。 直接將它們傳遞給 npx shadcn@latest init --preset <code>。

關鍵模式

這些是區分正確 shadcn/ui 程式碼的最常見模式。對於邊緣情況，請參閱上面連結的規則檔案。

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

元件選擇

需求	使用
按鈕/操作	Button 搭配適當的 variant
表單輸入	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
在 2–5 個選項之間切換	ToggleGroup + ToggleGroupItem
資料顯示	Table、Card、Badge、Avatar
導航	Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination
覆蓋層	Dialog (modal)、Sheet (側邊面板)、Drawer (底部面板)、AlertDialog (確認對話框)
回饋	sonner (toast)、Alert、Progress、Skeleton、Spinner
命令面板	Command 在 Dialog 內部
圖表	Chart (包裝 Recharts)
佈局	Card、Separator、Resizable、ScrollArea、Accordion、Collapsible
空狀態	Empty
選單	DropdownMenu、ContextMenu、Menubar
工具提示/資訊	Tooltip、HoverCard、Popover

關鍵欄位

注入的專案上下文包含以下關鍵欄位：

• aliases → 使用實際的別名前綴進行導入（例如 @/、~/），絕不硬編碼。
• isRSC → 當為 true 時，使用 useState、useEffect、事件處理器或瀏覽器 API 的元件需要在檔案頂部添加 "use client"。在建議使用此指令時，始終參考此欄位。
• tailwindVersion → "v4" 使用 @theme inline 塊；"v3" 使用 tailwind.config.js。
• tailwindCssFile → 定義自訂 CSS 變量的全域 CSS 檔案。始終編輯此檔案，不要創建新檔案。
• style → 元件視覺處理方式（例如 nova、vega）。
• base → 原始庫（radix 或 base）。影響元件 API 和可用 props。
• iconLibrary → 決定圖標導入。對於 lucide 使用 lucide-react，對於 tabler 使用 @tabler/icons-react 等。絕不要假定為 lucide-react。
• resolvedPaths → 元件、工具程式、鉤子等的確切檔案系統目標。
• framework → 路由和檔案約定（例如 Next.js App Router vs Vite SPA）。
• packageManager → 用於任何非 shadcn 的依賴安裝（例如 pnpm add date-fns vs npm install date-fns）。

參見 cli.md — info 命令 獲取完整欄位參考。

元件文件、範例與用法

運行 npx shadcn@latest docs <component> 獲取元件文件、範例和 API 參考的 URL。獲取這些 URL 以取得實際內容。

npx shadcn@latest docs button dialog select

在創建、修復、除錯或使用元件時，始終先運行 npx shadcn@latest docs 並獲取 URL。 這確保您使用的是正確的 API 和使用模式，而不是猜測。

工作流程

1. 獲取專案上下文 — 已在上方注入。如果需要刷新，再次運行 npx shadcn@latest info。
2. 首先檢查已安裝的元件 — 在運行 add 之前，始終檢查專案上下文中的 components 列表或列出 resolvedPaths.ui 目錄。不要導入尚未添加的元件，也不要重新添加已安裝的元件。
3. 查找元件 — npx shadcn@latest search。
4. 獲取文件和範例 — 運行 npx shadcn@latest docs <component> 獲取 URL，然後獲取它們。使用 npx shadcn@latest view 瀏覽尚未安裝的註冊表項目。要預覽已安裝元件的更改，使用 npx shadcn@latest add --diff。
5. 安裝或更新 — npx shadcn@latest add。更新現有元件時，首先使用 --dry-run 和 --diff 預覽更改（參見下面的 更新元件）。
6. 修復第三方元件中的導入 — 從社群註冊表（例如 @bundui、@magicui）添加元件後，檢查添加的非 UI 檔案中是否有硬編碼的導入路徑，如 @/components/ui/...。這些可能與專案的實際別名不匹配。使用 npx shadcn@latest info 獲取正確的 ui 別名（例如 @workspace/ui/components）並相應地重寫導入。CLI 會為其自己的 UI 檔案重寫導入，但第三方註冊表元件可能使用與專案不匹配的默認路徑。
7. 審查添加的元件 — 從任何註冊表添加元件或區塊後，始終讀取添加的檔案並驗證它們是否正確。檢查是否缺少子元件（例如沒有 SelectGroup 的 SelectItem）、缺少導入、不正確的組合或違反 關鍵規則。另外，將任何圖標導入替換為專案上下文中的 iconLibrary（例如，如果註冊表項目使用 lucide-react 但專案使用 hugeicons，則相應地交換導入和圖標名稱）。在繼續之前修復所有問題。
8. 註冊表必須明確指定 — 當用戶要求添加區塊或元件時，不要猜測註冊表。如果未指定註冊表（例如用戶說“添加一個登錄區塊”而未指定 @shadcn、@tailark 等），詢問要使用哪個註冊表。絕不要代表用戶默認一個註冊表。
9. 切換預設樣式 — 首先詢問用戶：重新安裝、合併還是跳過？
   • 重新安裝：npx shadcn@latest init --preset <code> --force --reinstall。覆蓋所有元件。
   • 合併：npx shadcn@latest init --preset <code> --force --no-reinstall，然後運行 npx shadcn@latest info 列出已安裝元件，然後對每個已安裝的元件使用 --dry-run 和 --diff 逐一進行智慧合併。
   • 跳過：npx shadcn@latest init --preset <code> --force --no-reinstall。僅更新配置和 CSS，保持元件不變。
   • 重要提示：始終在用戶的專案目錄內運行預設命令。CLI 會自動保留來自 components.json 的當前基礎（base vs radix）。如果必須使用暫存/臨時目錄（例如用於 --dry-run 比較），請顯式傳遞 --base <current-base> — 預設程式碼不編碼基礎。

更新元件

當用戶要求從上游更新元件同時保留其本地更改時，使用 --dry-run 和 --diff 進行智慧合併。絕對不要直接獲取原始檔案並手動合併，因為這樣會丟失本地更改。使用工作流程：

1. npx shadcn@latest add <component> --dry-run --diff 查看上游更改。這將顯示差異。
2. 如果存在衝突，npx shadcn@latest add <component> --overwrite 暫存新版本，然後使用編輯器手動合併差異。
3. 審查並套用合併後的檔案。

對於大規模更新，使用暫存目錄來比較所有元件：

# 使用暫存目錄
mkdir -p /tmp/shadcn-update
cd /tmp/shadcn-update
npx shadcn@latest init --preset <code> --base <current-base>
npx shadcn@latest add --all --overwrite

# 與當前專案進行差異比較
cd /path/to/project
diff -r /tmp/shadcn-update/src/components/ui ./src/components/ui

安裝前提

• 專案必須已經初始化 shadcn init。如果沒有，用戶必須先運行 npx shadcn@latest init。
• 如果專案還沒有初始化，添加元件將失敗。在繼續之前先初始化。