shadcn

shadcn skill 概览

shadcn skill 是做什么的

shadcn skill 的作用，是让 AI 助手在真实的 shadcn/ui 项目里正确工作：找到现有组件、用正确的 CLI 安装所需项、基于已有 primitives 组合页面，并避免在不同 preset 和组件家族之间常见的 API 用错问题。它最适合那些不只是想“生成一个按钮”，而是希望输出真正遵循 components.json、已安装的 registry items、当前模板，以及 base 与 radix 差异的场景。

谁适合使用 shadcn skill

最适合的读者包括：

• 已经在使用 shadcn/ui 的开发者
• 正在采用 preset 或基于 registry 的 UI 工作流的团队
• 会让 AI 去新增或重构表单、对话框、设置页、仪表盘或主题相关功能的人
• 希望助手在写 JSX 之前先检查项目上下文的任何人

如果你的项目并不使用 shadcn/ui、components.json 或 shadcn CLI，那这个 skill 大概率就过于垂直了。

它真正要解决的问题

用户想要的并不只是仓库摘要，而是希望助手能够：

1. 识别项目当前的 shadcn 配置，
2. 优先选用已有组件，而不是凭空造新组件，
3. 使用正确的 CLI 命令和文档里真实存在的参数，
4. 按照这个组件库推荐的模式去组合 UI，
5. 避免一些不容易第一眼发现但会出问题的细节，比如错误的 trigger 组合方式、漏掉必要的 group wrapper，或表单校验接线不正确。

这正是 shadcn skill 相比普通 UI prompt 更有价值的地方。

shadcn skill 与通用提示词的区别

它最核心的差异，体现在这些实操层面：

• 从 npx shadcn@latest info --json 的项目上下文开始，而不是盲写
• 在自定义实现之前，优先强调 search、view 和 docs
• 把 rules/composition.md、rules/forms.md、rules/styling.md、rules/base-vs-radix.md 这类文件里的项目规则编码进流程
• 覆盖主题和 preset 切换，而不只是给你几个组件代码片段
• 包含通过 MCP 做 registry 搜索和安装的工作流指引

简而言之，shadcn skill 关注的不是“写 React”，而是“为当前这个 shadcn 配置写对的 React”。

使用 shadcn skill 前需要知道的限制

在真正依赖这个 skill 之前，请先明确这些限制：

• 它默认项目能通过包管理器运行 shadcn CLI：npx、pnpm dlx 或 bunx --bun
• 它只在文档支持的 CLI 参数范围内工作；skill 会明确提醒不要凭空猜 flag
• 很多高质量输出都依赖一个有效的 components.json
• API 细节会因 preset 不同以及 base / radix 差异而变化，所以照搬示例很可能是错的

如何使用 shadcn skill

shadcn skill 的安装与运行上下文

先按目录的标准安装流程把 skill 加到你的 AI 环境里，然后在一个真实包含或计划引入 shadcn 配置的仓库中使用它。实际使用时，仓库侧的条件往往比 skill 的安装命令更重要：助手需要能访问你的项目文件，最好还能够运行 shadcn CLI。

在目标项目中，关键的运行命令包括：

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

如果项目使用的是其他包管理器，请替换成 pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。

让 shadcn skill 输出前，先读这些文件

如果你想更快、更准确地使用 shadcn，建议大致按这个顺序检查文件：

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

这个顺序有效的原因是：

• SKILL.md 定义了触发条件和整体工作流
• cli.md 能避免助手猜命令、猜参数
• rules/ 下的文件记录了通用代码生成最容易犯的错
• 当你需要主题安全的样式，而不是随手写 Tailwind 颜色 hack 时，customization.md 很关键
• 如果你的助手可以通过 MCP 浏览 registry，而不是直接跑 shell 命令，那么 mcp.md 就很重要

每个 shadcn 任务都先做项目探测

最值得优先执行的一步是：

npx shadcn@latest info --json

这条命令会告诉助手项目已经配置了什么，包括组件和项目上下文。它尤其适合用于：

• 检查 components.json 是否存在
• 识别已经安装了哪些组件
• 发现那些会影响代码写法的配置细节
• 确认项目使用的 package runner，避免给出错误的命令示例

如果你跳过这一步，shadcn skill 的效果就会更接近一个普通提示词。

把模糊需求改写成高质量的 shadcn 提示

弱提示：

Build me a profile dialog with shadcn.

更好的提示：

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

为什么这个版本更强：

• 它强制先做项目探测
• 它明确了对 preset 敏感的行为要求
• 它写清了图标和样式约束
• 它要求在依赖缺失时先给安装步骤

先用 search 和 docs，再写自定义代码

高质量的 shadcn 工作流通常是：

1. 先在 registry 里搜索现有组件，
2. 查看 docs 和示例，
3. 安装缺少的部分，
4. 再去组合页面。

常用命令如下：

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

这一步对于 forms、overlays、navigation 和 empty states 尤其重要，因为 skill 的规则更偏向采用库内既有模式，而不是临时手写一堆 div 结构。

用现有 building blocks 组合页面，而不是整块手搓 UI

当你让助手做“组合”而不是“一次性定制大组件”时，shadcn skill 的效果最好。比较好的任务描述方式包括：

• “settings page = Tabs + Card + form controls”
• “dashboard = Sidebar + Card + Chart + Table”
• “empty state = Empty component, not a custom centered div”
• “callout = Alert, not hand-rolled border boxes”

这和 skill 的推荐工作流一致：优先使用现成组件，只在确有必要时再调整 variant 和 wrapper。

认真区分 base 与 radix 的差异

很多人接入 shadcn 时最大的阻碍之一，就是误以为所有 shadcn 示例都能互换。事实并不是这样。

这个 skill 对 base 和 radix 提供了明确指引，包括：

• asChild 与 render
• trigger 组合方式的差异
• 某些只在 base 场景里需要的 nativeButton={false}
• Select、ToggleGroup、Slider、Accordion 等组件的 API 差异

如果你的 prompt 没有说明使用的是哪种 setup，就应该让助手通过 npx shadcn@latest info 先识别出来。

按能适配主题的方式写样式

在 shadcn for UI Design 的场景里，效果更好的通常不是硬编码 Tailwind 颜色，而是使用 semantic tokens 和 CSS variables 驱动的主题方案。

优先使用：

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

尽量避免默认写成：

• bg-red-500
• text-gray-400
• 大量手动 dark: 覆盖

原因在于，customization.md 已经说明组件样式是从 CSS variables 继承的。如果助手用的是 semantic tokens，你的设计在浅色/深色主题以及不同 preset 之间都会更容易扩展，也更不容易乱。

按 shadcn 的方式处理表单

从 evals 和 rules 可以看出，表单质量是这个 skill 的重点之一。更符合 shadcn 方式的表单实现，通常意味着：

• 使用已有的字段布局模式，而不是简单堆叠原始 div
• 用 data-invalid 和 aria-invalid 标记无效状态
• 对彼此独立的开关型偏好使用 Switch
• 在规则要求的地方优先用 gap-*，而不是习惯性写 space-y-*

如果你的任务包含校验逻辑，请明确写出来。否则很多助手虽然能生成“看起来像那么回事”的表单，但会和库本身的约定不一致。

编辑器支持时，优先结合 MCP 使用 shadcn skill

如果你的环境支持 MCP，shadcn skill 在处理 registry 相关操作时会更稳。mcp.md 记录了这些能力对应的工具：

• 列出项目 registries
• 搜索 registry items
• 查看 item 详情和文件内容
• 获取示例
• 安装 items

当你希望助手用对话式方式浏览 registry，而不是只依赖 CLI 输出时，这会很有帮助。但它不能替代 info --json 对项目配置的探测作用。

shadcn skill 的实用提示模板

如果你希望 shadcn skill 给出更高质量的结果，可以直接用这个模板：

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

shadcn skill 常见问题

shadcn skill 只是用来安装组件的吗？

不是。shadcn install 相关任务只是其中一部分，shadcn skill 的范围更广：项目检查、registry 搜索、组件组合、主题处理、问题排查、preset 切换，以及 API 正确的重构，都在它的能力范围内。

shadcn skill 对新手友好吗？

如果你已经熟悉 React 和包管理器，那它是友好的。这个 skill 会把助手引导到正确的命令和规则上，减少拍脑袋猜的成分。但如果你需要的是从零开始学习 React、Tailwind 或设计系统，那它就不算特别新手友好。

什么情况下 shadcn skill 比普通 prompt 更合适？

当正确性高度依赖项目上下文时，就该用 shadcn skill，例如：

• 已经存在 components.json
• 需要匹配当前已安装的组件
• 需要区分 base 与 radix 行为
• 只能使用文档中真实支持的 CLI 参数
• 要保留 theme tokens 和组件库自己的组合规则

普通 prompt 也许能生成“看起来没问题”的 JSX，但更容易漏掉安装步骤，或者把组件 API 用错。

什么情况下不该用 shadcn skill？

以下情况建议跳过：

• 你的项目根本没用 shadcn/ui
• 你只需要通用的 HTML/CSS 原型
• 你想要与设计系统无关的回答
• 助手既不能读文件也不能跑命令，而你又无法手动补充必要上下文

在这些场景下，使用更通用的前端 skill 反而更合适。

这个 skill 能帮助做 shadcn for UI Design 的设计决策吗？

可以，尤其是在组合方式和主题处理上。它会推动助手优先使用可复用的 primitives、semantic color tokens、正确的 overlay 模式，以及比一次性手工布局更容易维护的组件结构。

AI 输出里，shadcn 使用通常会在哪里出错？

常见失败点包括：

• 编造不受支持的 CLI 参数
• 在 base 和 radix 之间用了错误的 trigger 组合方式
• 明明已有 registry 组件，却重新手搓了一个自定义 UI
• 使用原始颜色类，和主题系统冲突
• 漏掉必需的子组件，比如 title、group 或 fallback

而这些恰恰就是这个 skill 重点要收紧的地方。

如何提升 shadcn skill 的使用效果

预先把缺失上下文补给 shadcn skill

提升效果最明显的办法，是给更完整的输入。建议至少说明：

• 使用的 framework 或 template（next、vite、astro 等）
• 是否存在 components.json
• 如果已知，当前是 base 还是 radix
• 目前的图标集
• 目标组件或页面类型
• 任务是安装、重构，还是修 bug

哪怕只是多补一句具体上下文，也常常足以避免助手选错 API。

组件可能缺失时，先让 shadcn skill 给命令，再写代码

如果你不确定项目里是否已经安装了所需组件，可以这样提示：

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

这样做能显著提升结果可用性，因为它把“环境变更”和“实现代码”拆开了，输出会更容易验证，也更容易直接落地。

对脆弱组件类型，要求 shadcn skill 严格遵守规则

对于 forms、dialogs、dropdowns、sheets、drawers 和 selects，最好明确要求助手遵循 rule 文件。示例：

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

这很重要，因为很多低质量生成内容表面看起来没问题，但实际上会破坏可访问性或组件组合契约。

通过明确设计约束来提升 shadcn skill 输出质量

好的 UI prompt 不只是“做得现代一点”。你应该写清楚这些约束，例如：

• 只能使用 semantic tokens
• 不要直接使用原始调色板 utilities
• dark mode 必须无需手动覆盖也能正常工作
• 优先使用现有 variants，再考虑自定义 classes
• 优先使用库里的 empty states、alerts、separators、badges 和 skeletons

这些细节对 shadcn for UI Design 的首轮输出质量有实质影响。

用定向修正迭代，而不是每次都整段重写

拿到第一版结果后，不要只说“再试一次”。更有效的说法是：

• “Refactor this to use installed shadcn components only.”
• “Make this valid for base, not radix.”
• “Replace raw color classes with semantic tokens.”
• “Add the missing title/fallback/group wrappers required by shadcn.”
• “Show the exact shadcn add commands for anything assumed.”

这种方式能保留已经做对的部分，只修正最容易出错的关键点。

用仓库里最强的信号校验 shadcn skill 输出

如果你想提高可信度，可以把输出对照这些文件逐项检查：

• cli.md：检查命令和参数
• rules/composition.md：检查结构是否正确
• rules/base-vs-radix.md：检查 API 是否适配
• rules/forms.md：检查校验和布局模式
• rules/styling.md 与 customization.md：检查样式是否对主题安全
• evals/evals.json：对照仓库里“好输出”在实际是什么样

这是判断 shadcn skill 产出的内容到底是“贴合仓库规则”，还是“只是通用 UI 代码”的最快方法。