前言¶

用 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 组件

前言¶

这是什么¶

核心功能¶

安装与启用¶

典型用法¶

适用场景与注意事项¶

小结¶

精选优惠券

相关文章