前言¶

用 AI 寫 shadcn/ui，最常見的問題不是它不會寫 Button，而是它寫的那套對不上你的項目。別名寫成 @/components/ui，實際倉庫用的是 @workspace/ui/components；圖標默認 lucide-react，項目已經換成 Tabler；表單用手寫 div + space-y-*，官方組合卻是 FieldGroup + Field；底層原語是 Base UI，它還在用 Radix 的 asChild。組件能跑，風格、路徑和 API 卻全是另一套記憶。

shadcn/ui 本身不是傳統的 npm 組件包，而是通過 CLI 把源碼寫進項目。倉庫 shadcn-ui/ui 目前超過 12 萬 star，組件按項目的 components.json 生成。2026 年 3 月發佈的 CLI v4 專門補了一塊給編程助手用的上下文：官方 Skill。裝上之後，助手先讀你的項目配置，再決定搜哪個 registry、裝哪個組件、用哪套組合規則。

這是什麼¶

一句話定位：shadcn 是 shadcn/ui 官方維護的 Agent Skill，用來管理組件的搜索、安裝、修復、調試、樣式和組合（含聊天界面），並在有 components.json 的項目裏注入真實配置。

來源與歸屬：

維護方：shadcn-ui 組織，代碼在官方倉庫 shadcn-ui/ui
目錄：https://github.com/shadcn-ui/ui/tree/main/skills/shadcn
文檔：https://ui.shadcn.com/docs/skills
SKILL.md 裏的 name 是 shadcn；user-invocable 爲 false，不是斜槓命令，而是檢測到相關任務時自動加載

它解決的核心問題很具體：助手不再憑訓練數據猜組件 API，而是先跑 shadcn info --json，拿到框架、Tailwind 版本、別名、底層原語庫（base / radix / aria）、圖標庫、已安裝組件和解析後的文件路徑，再按官方規則生成代碼。

核心功能¶

官方文檔把 Skill 覆蓋的知識分成幾塊，和倉庫裏的參考文件一一對應。

1、項目上下文。 每次相關交互都會執行 shadcn info --json。SKILL.md 強調這些字段必須跟着項目走，不能寫死：

aliases：導入前綴，可能是 @/，也可能是 ~/ 或工作區路徑
isRSC：爲 true 時，用到 useState、useEffect、事件處理或瀏覽器 API 的文件要加 "use client"
tailwindVersion：v4 用 @theme inline，v3 用 tailwind.config.js
tailwindCssFile：自定義 CSS 變量只改這個文件，不要另建一份
base：底層原語庫，決定組件 API（例如 Radix 用 asChild，Base UI 用 render）
iconLibrary：決定圖標從哪個包導入，不能默認當成 lucide-react
framework、packageManager、resolvedPaths：路由約定、裝依賴的命令、組件實際落盤路徑

2、CLI 用法。 Skill 內附 cli.md，覆蓋 init、add、search、view、docs、info、apply、preset、build 等命令，以及 --dry-run、--diff、preset 和模板。CLI 命令必須按項目的包管理器來跑：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。

3、組合規則。 rules/ 目錄裏有 Incorrect / Correct 對照，強制執行幾條常見約束：

表單用 FieldGroup + Field，不要用裸 div 加 space-y-*
2–7 個選項用 ToggleGroup，不要手寫一組帶選中態的 Button
間距用 flex + gap-*，不用 space-x-* / space-y-*
顏色用語義 token（bg-primary、text-muted-foreground），不用 bg-blue-500
Dialog / Sheet / Drawer 必須有 Title；Avatar 必須有 AvatarFallback
先搜已有組件，再寫自定義 markup：提示用 Alert，空狀態用 Empty，加載用 Skeleton

4、主題、Registry 與 MCP。 customization.md 說明 CSS 變量、OKLCH、暗色模式和 Tailwind v3 / v4 的差異；registry.md 說明如何寫和發佈自定義 registry；mcp.md 說明 MCP 服務器，用來在 registry 裏搜索、瀏覽和安裝條目。官方提示：registry 操作用 MCP，項目配置仍用 shadcn info，MCP 沒有等價接口。

安裝與啓用¶

官方文檔給出的安裝命令是：

pnpm dlx skills add shadcn/ui

skills.sh 上的等價寫法是 npx skills add shadcn/ui。這會把 Skill 裝進當前項目；之後在處理 shadcn/ui 組件時，助手會自動加載。也可以指定倉庫路徑：

npx skills add https://github.com/shadcn-ui/ui --skill shadcn

skills 是 Vercel Labs 維護的通用安裝器，支持 Claude Code、Cursor、Codex、OpenCode 等。項目級和用戶級目錄不同，常見幾項如下：

工具	項目目錄	用戶目錄（`-g`）
Claude Code	`.claude/skills/`	`~/.claude/skills/`
Cursor	`.agents/skills/`	`~/.cursor/skills/`
Codex	`.agents/skills/`	`~/.codex/skills/`

只給某一個工具裝，可以加 --agent，例如 --agent cursor 或 --agent claude-code。

Skill 能自動加載，前提是項目裏有 components.json。這個文件由 CLI 的 init 生成，用來描述框架、別名和 registry。官方說明：只靠複製粘貼組件時可以沒有它；要用 CLI 往項目里加組件，就必須有。沒有這份文件，Skill 的項目檢測不會激活，助手也就讀不到真實配置。

已有項目可以先初始化：

pnpm dlx shadcn@latest init

如果還要用自然語言搜 registry、裝 block，可以額外開 MCP。Cursor 寫在項目的 .cursor/mcp.json：

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Claude Code 寫在 .mcp.json，字段相同。也可以讓 CLI 代寫配置：

pnpm dlx shadcn@latest mcp init --client claude
pnpm dlx shadcn@latest mcp init --client cursor

Codex 需要手動改 ~/.codex/config.toml，CLI 不會自動更新這份文件。

典型用法¶

官方文檔給的提問方式很直接，例如：

加一個帶郵箱和密碼的登錄表單
做設置頁，表單用來更新個人資料
搭 Dashboard：側邊欄、統計卡片、數據表格
切換到某個 --preset 代碼
從 @tailark 加一個 hero

助手內部應按 Skill 規定的順序工作，而不是直接開寫 JSX。

1、讀項目配置。 上下文裏已經注入過一次；需要刷新時再跑：

npx shadcn@latest info --json

2、先看已經裝了什麼。 用 info 返回的 components 列表，或直接看 resolvedPaths.ui 目錄。已經在項目裏的組件不要再 add 一遍，也不要 import 尚未安裝的文件。

3、搜索，再讀文檔。 生成或修改某個組件前，先拿文檔和示例 URL：

npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest docs button dialog select
npx shadcn@latest view @shadcn/button

4、安裝或更新。 更新已有組件時，先預覽，再決定要不要覆蓋：

npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx

--overwrite 必須得到明確同意。用戶說「全部更新」時，也要先確認。

5、Preset。 不要手工解碼 preset 碼或拼接 URL，交給 CLI：

npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest apply a2r6bw --only theme,font
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset resolve

切換 preset 時，Skill 要求先問清楚：覆蓋（overwrite）、部分更新（theme / font）、合併（merge）還是跳過組件只改配置。apply 只適用於已經有 components.json 的項目，並且會保留當前的 base。

組合代碼以官方示例爲準，不要把 Label 和 Input 隨便塞進 div：

<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

校驗狀態寫在正確的節點上：data-invalid 放在 Field，aria-invalid 放在控件本身。

適用場景與注意事項¶

適合這些情況：

已經在用 shadcn/ui，或者準備 init 一套新項目，希望助手按倉庫裏的別名、圖標庫和原語庫寫代碼
要從官方 registry、社區 registry（如 @magicui、@tailark）或 owner/repo 安裝組件、block
要做登錄表單、設置頁、Dashboard、聊天界面這類需要正確組合多個組件的頁面
要維護自定義 registry，或用 MCP 在多個 namespace 之間搜索

使用時有幾條硬限制，官方資料寫得很明確：

沒有 components.json，Skill 不會按「當前項目」工作。 複製粘貼組件可以沒有這份文件，CLI 和這份 Skill 不行。
用戶沒指定 registry 時，不要替他猜。 只說「加一個登錄 block」、沒寫 @shadcn / @tailark / owner/repo，應該先問用哪個源。
第三方 registry 的導入路徑可能是寫死的。 CLI 會改自己的 UI 文件；社區組件裏仍可能出現 @/components/ui/...。裝完後要對照 info 裏的真實 alias 改導入，並把圖標換成項目的 iconLibrary。
Toast 跟 base 走。 Base UI 項目用 toast 組件導出的 toast；Radix 和 React Aria 項目用 sonner。
MCP 替代不了 info。 搜組件、看源碼、拿安裝命令可以用 MCP 工具；框架、別名、Tailwind 版本仍然要靠 CLI 的 info。
命令不要混用包管理器。 Skill 允許的 Bash 工具是 npx shadcn@latest *、pnpm dlx shadcn@latest * 和 bunx --bun shadcn@latest *，以 packageManager 字段爲準。

倉庫裏同一 pack 還有一個 migrate-radix-to-base Skill，專門處理 Radix 遷到 Base UI；日常裝組件、寫頁面用的是本文這份 shadcn。

小結¶

shadcn/ui 把組件以源碼形式放進項目，配置全在 components.json 裏。官方 Skill 做的事情，就是把這份配置和組合規則交給編程助手：先 info，再 search / docs，最後才 add。CLI v4 之後，preset、dry-run 和 MCP 也寫進了同一套工作流。

官方地址：

Skill 源碼：https://github.com/shadcn-ui/ui/tree/main/skills/shadcn
文檔：https://ui.shadcn.com/docs/skills
CLI：https://ui.shadcn.com/docs/cli
MCP：https://ui.shadcn.com/docs/mcp
安裝目錄：https://www.skills.sh/shadcn/ui

shadcn Skill：讓 AI 按項目配置搜索、安裝和組合 shadcn/ui 組件

前言¶

這是什麼¶

核心功能¶

安裝與啓用¶

典型用法¶

適用場景與注意事項¶

小結¶

精选优惠券

shadcn Skill：讓 AI 按項目配置搜索、安裝和組合 shadcn/ui 組件

前言¶

這是什麼¶

核心功能¶

安裝與啓用¶

典型用法¶

適用場景與注意事項¶

小結¶

精选优惠券

相關文章