shadcn-skill

July 11, 2026 · 9 min read

shadcn/ui 官方 Skill，让 AI 写符合规范的 shadcn 项目代码。

它是什么：放在 shadcn-ui/ui 仓库 skills/shadcn/ 下的官方 Skill
解决的痛点：AI 写 shadcn 项目普遍走偏——用原生 div 替代组件、写自定义样式覆盖组件、手撸 chat UI
核心机制：限定只跑 shadcn@latest CLI + 6 类强制 Critical Rules
关键能力：shadcn mcp 给 AI 加 search/view/install 工具
配套：--preset 主题码一键切换整套主题 + 组件
结论：做 shadcn 项目必装，别让 AI 瞎写

What：放在官方仓库里的 Skill

shadcn-ui/ui 仓库（截至 2026-07 已 11.7 万 Star）根目录有个 skills/shadcn/ 目录，里面是官方为 AI Agent 准备的 Skill——SKILL.md + 4 个细分文档（cli / customization / mcp / registry）+ 6 个 rules/ 规则文件。

不是社区玩具，是 shadcn 团队自己维护的官方版本，跟 CLI、registry、组件库同步升级。

仓库布局：

shadcn-ui/ui/skills/shadcn/
├── SKILL.md              # 主入口（Agent 加载）
├── cli.md                # CLI 命令参考
├── customization.md      # 主题 / 定制
├── mcp.md                # MCP server 配置
├── registry.md           # Registry 制作规范
├── rules/                # 6 类强制规则
│   ├── styling.md
│   ├── forms.md
│   ├── composition.md
│   ├── icons.md
│   ├── base-vs-radix.md
│   └── chat.md
├── agents/               # 子 Agent 配置
├── evals/                # 评测用例
└── assets/               # 模板资源

SKILL.md 是触发入口，正文控制在约 300 行；详细规则都在 rules/ 子文件里——典型的"渐进式披露"组织方式，符合 Anthropic Agent Skills 设计的 progressive disclosure 原则。

Why：AI 写 shadcn 项目普遍走偏

不用这个 Skill 时，AI 写 shadcn 项目很容易写出"看得过去但完全错误"的代码。我让 Claude Code 直接"写一个 settings 页面"试过几次，几乎都跑偏——

典型错误清单：

错误	AI 写的版本	正确版本
表单布局	`<div className="space-y-4">` + `<label>`	`<FieldGroup>` + `<Field>`
间距	`<div className="space-x-2">`	`<div className="flex gap-2">`
等宽高	`<Avatar className="w-10 h-10">`	`<Avatar className="size-10">`
暗色模式	`className="bg-white dark:bg-gray-900"`	`className="bg-background text-foreground">`
颜色	`bg-blue-500 text-white`	`bg-primary text-primary-foreground`
Select 选项	直接 `<SelectItem>`	`<SelectItem>` 必须包在 `<SelectGroup>` 里
Chat UI	手撸 div + ResizeObserver 跟底	`<MessageScroller>` + `<Bubble>`
Loading	`animate-pulse` 自定义 div	`<Skeleton>`
Toast	自建 toast 系统	`sonner` 的 `toast()`
空状态	`<div className="text-center py-8">`	`<Empty>` 组件
提醒框	`<div className="p-4 bg-yellow-100">`	`<Alert>` 组件

根本原因：AI 训练数据里 shadcn 项目占少数，遇到表单、Chat 这种"看起来很简单"的场景，倾向自己撸——撸出来代码能跑，但跟项目其他部分不一致，下次升级就全乱。

How：4 大核心原则 + 6 类强制规则

4 大核心原则（写入 SKILL.md 正文）

Use existing components first. Use npx shadcn@latest search to check registries
Compose, don't reinvent. Settings page = Tabs + Card + form controls
Use built-in variants before custom styles. variant="outline", size="sm"
Use semantic colors. bg-primary, text-muted-foreground — never bg-blue-500

翻译成人话：

先搜现有组件——npx shadcn@latest search 搜遍官方和社区 registry，不要手撸
组合而非重写——Settings 页 = Tabs + Card + 表单控件，不要把整个组件重做
优先用 variant——variant="outline" 而不是 className="border-2 ..."
永远用语义色——bg-primary 而不是 bg-blue-500，主题切换才不掉链

6 类 Critical Rules（指向 rules/ 子文件）

SKILL.md 里把规则按 6 类组织，每个分类下都有 Incorrect / Correct 代码对比：

类别	文件	核心约束
Styling	`styling.md`	`className` 只管布局、`flex gap-` 替代 `space-`、`size-*` 等宽高、`truncate` 简写、不手写 `dark:`
Forms	`forms.md`	`FieldGroup` + `Field` 必用、`InputGroup` 用 `InputGroupInput`、验证用 `data-invalid`
Composition	`composition.md`	Item 必须在 Group 里、Dialog/Sheet/Drawer 必须有 Title、Card 用完整 5 段结构
Icons	`icons.md`	Button 里图标用 `data-icon`、图标不写尺寸 class
Chat	`chat.md`	Chat UI 走 `MessageScroller` / `Message` / `Bubble`，不手撸
Base vs Radix	`base-vs-radix.md`	自定义触发器根据 base 字段选 `asChild` (radix) 或 `render` (base)

这些不是建议，是 强制约束——SKILL.md 写了 "These rules are always enforced"。

例子：spacing 规则

最容易被 AI 违反的 spacing 规则：

// ❌ AI 默认这么写
<div className="space-y-4">
  <div>...</div>
  <div>...</div>
</div>

// ✅ 强制写法
<div className="flex flex-col gap-4">
  <div>...</div>
  <div>...</div>
</div>

为什么不用 space-*：方向不灵活（要水平间距就 GG），跟 flex 嵌套时容易乱——这是 shadcn 团队的明确取舍。

工具集：CLI + MCP 双通道

CLI 限定

SKILL.md 用 allowed-tools 限定 AI 只能跑 shadcn@latest 这套命令：

allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)

不允许：自己 fetch GitHub raw 文件、不允许手写 registry.json 解析、不允许编 --package-manager 这种不存在的 flag（CLI 从 lockfile 自动识别）。

最常用的 4 个命令：

命令	用途
`npx shadcn@latest init`	在现有项目里初始化，或 `--name` 创建新项目
`npx shadcn@latest add <comp>`	加组件（支持 `--dry-run` / `--diff` / `--view` 预览）
`npx shadcn@latest search`	跨 registry 模糊搜索
`npx shadcn@latest apply <preset>`	一键应用主题码或命名预设

--dry-run 系列：

# 预览改动不写文件
npx shadcn@latest add button --dry-run

# 看 diff（前 5 个文件）
npx shadcn@latest add button --diff

# 看指定文件 diff
npx shadcn@latest add button --diff button.tsx

加组件前先 --dry-run，AI 写错的概率能降低 80%——跟"先 PR 后合并"是同一个套路。

MCP server

shadcn mcp 启动一个 stdio MCP server，给 AI 加 7 个搜索/查看/安装工具：

工具	用途
`shadcn:get_project_registries`	读 `components.json` 拿当前项目的 registry 列表
`shadcn:list_items_in_registries`	列出所有 registry 的所有 item
`shadcn:search_items_in_registries`	模糊搜（"find me a hero"）
`shadcn:view_items_in_registries`	查看 item 文件内容
`shadcn:get_item_examples_from_registries`	找使用示例和 demo
`shadcn:get_add_command_for_items`	生成 install 命令
`shadcn:get_audit_checklist`	验证清单（imports / deps / lint / TS）

一行 shadcn mcp init 写对应编辑器的 .mcp.json——Claude Code / Cursor / VS Code / OpenCode / Codex 全部支持。

tip

shadcn mcp 解决的是另一类问题：CLI 一次只能加一个组件，MCP 让 AI 在写代码之前先搜/看示例，决策质量更高。

主题：preset 一键换皮

主题是 shadcn 的高频场景——前端项目做到一半想换色系，重写组件成本巨大。apply --preset 一行解决：

# 命名预设（nova / base / radix 等）
npx shadcn@latest apply --preset nova

# 主题码（ui.shadcn.com 上生成）
npx shadcn@latest apply a2r6bw

# 自定义 URL
npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue"

apply 不只是换色——会覆盖字体、CSS 变量、检测到的 UI 组件。想保留已有组件用 init --preset nova --force --no-reinstall。

主题本身通过 CSS 变量工作：globals.css 里 :root 和 .dark 各定义一套，bg-primary 这种语义 class 自动跟随——这是为什么强调"永远用语义色、不要写 bg-blue-500"，写死了换主题就失效。

实战：装这个 Skill

SKILL.md 不在 npm 上，跟 Agents365-ai/drawio-skill 那种独立 Skill 仓库不一样——它是官方 shadcn-ui/ui 仓库的子目录。要装：

# 复制 skill 目录到 Claude Code 全局配置
mkdir -p ~/.claude/skills/
cp -r /path/to/shadcn-ui/ui/skills/shadcn ~/.claude/skills/

# 重启 Claude Code 会话

SKILL.md 的 description 写得很精确：

description: Manages shadcn components and projects — adding, searching,
fixing, debugging, styling, and composing UI, including chat interfaces.
Provides project context, component docs, and usage examples.
Applies when working with shadcn/ui, component registries, presets,
--preset codes, or any project with a components.json file.
Also triggers for "shadcn init", "create an app with --preset",
or "switch to --preset".

——"何时调"写得很清晰，AI 几乎不会误触或漏触。

小结

shadcn-skill = 官方 shadcn-ui 团队维护的 AI Skill，放在 shadcn-ui/ui 仓库 skills/shadcn/ 下
解决 AI 写 shadcn 代码走偏（手撸 div、自定义样式、bg-blue-500、手撸 chat UI 等）
4 原则 + 6 类强制规则 = 几乎所有常见错误都拦得住
shadcn@latest CLI 限定 + shadcn mcp 工具集 = AI 不用再自己解析 registry
--preset 主题码 = 一键换整套主题，不改组件代码

做 shadcn 项目必装，不是可选项。

References

shadcn-ui/ui 仓库 —— 官方 Skill 所在地，11.7 万 Star
Anthropic Agent Skills 官方文档 —— Skill 渐进式披露设计
drawio-skill 实战案例 —— 另一种官方 + 社区双线并存的 Skill 范式
怎么写一个 Agent Skill —— 通用 Skill 写作规约（最小目录 + 4 坑）
Skills Manager —— 多 AI 工具的 Skill 统一管理
book-to-skill —— 把结构化知识拆成 Skill 的另一种范式
shadcn/ui 官网 —— 组件浏览 + preset 生成器

What：放在官方仓库里的 Skill​

Why：AI 写 shadcn 项目普遍走偏​

How：4 大核心原则 + 6 类强制规则​

4 大核心原则（写入 SKILL.md 正文）​

6 类 Critical Rules（指向 rules/ 子文件）​

例子：spacing 规则​

工具集：CLI + MCP 双通道​

CLI 限定​

MCP server​

主题：preset 一键换皮​

实战：装这个 Skill​

小结​

References​