shadcn作者 shadcn

shadcn Skill.

Claude Code 和 Codex 的 UI 设计 skill：在项目中添加、搜索、修复、样式化和组合 shadcn 组件。

Web & UI
UI 代码

shadcn-ui/ui · skills/shadcn/SKILL.mdSKILL.md

--- name: shadcn 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". --- ## Current Project Context ## Principles ## Critical Rules ## Key Patterns ## Component Selection ## Key Fields

前言和章节标题读取自上游文件，时间为 2026-09-14 · 完整内容 19,427 字符

01 功能说明

shadcn Skill 在 Claude Code 和 Codex 中的作用

摘要、工作流与产物，均读自该 skill 的 SKILL.md。

来自 SKILL.md读取于 2026-09-14 · 非实际运行记录

以 skill 自身的术语

此 skill 通过添加、搜索、修复和组合组件来管理 shadcn/ui 项目。它会从 components.json 中注入实时项目上下文，针对表单、样式、组合、图标和聊天界面强制执行特定框架的规则，并使用 shadcn CLI 完成所有操作。组件会通过 npx shadcn@latest（或项目所用的包管理器）以源代码形式安装。

当处理 shadcn/ui、组件注册表、预设代码，或任何带有 components.json 文件的项目时，该 skill 会生效。它涵盖 RSC 指令、Tailwind v3/v4、Base UI 与 Radix 基础组件的对比、图标库检测，以及 monorepo 布局。每条命令都会引用项目实际的别名、包管理器和解析后的路径。

它产出什么

添加到项目已解析 ui 路径下的 shadcn 组件源代码文件
更新时合并的组件文件，在应用上游更新的同时保留本地修改

查看示例提示词 ↗

工作方式

01
注入项目上下文
运行 npx shadcn@latest info --json 以获取项目配置、已安装组件、别名、RSC 标志、Tailwind 版本、图标库、基础库（radix 或 base），以及解析后的路径。
02
在编写自定义 UI 前先搜索注册表
使用 npx shadcn@latest search 在 shadcn 注册表和社区注册表中查找符合需求的现有组件。
03
获取组件文档和示例
运行 npx shadcn@latest docs <component> 获取文档和示例链接，然后获取这些内容，以便在创建或修复组件前验证 API 使用是否正确。
04
使用 CLI 添加或更新组件
使用 npx shadcn@latest add 安装组件。
05
修复第三方组件中的导入
从社区注册表添加组件后，检查非 UI 文件中是否存在类似 @/components/ui/... 的硬编码路径
06
检查并验证已添加的组件
读取所有已添加的文件，检查是否缺少子组件、组合是否错误、是否违反关键规则以及图标导入是否不匹配。

02 找到适合场景

何时使用 shadcn Skill

在 Claude Code 或 Codex 中使用 shadcn skill 进行此类 UI 设计工作。适用范围和限制来自该 skill 自身的文件。

适合场景

在已有 components.json 文件的现有项目中使用 shadcn/ui 组件构建 UI
使用预设代码或命名预设（如 nova 或 vega）初始化新的 shadcn 项目
使用 MessageScroller、Message、Bubble、Attachment 和 Marker 构建聊天或对话界面

了解边界

手动从 GitHub 获取组件文件，而不是使用 CLI
用户未指定使用哪个 registry 时默认使用某个 registry
未经用户明确同意使用 --overwrite 更新组件
编造项目上下文中不存在的功能、集成或文件名

需要提供的信息

组件或区块名称要添加或搜索的 shadcn 组件名称（button、dialog、select）或 registry 项（@magicui/shimmer-button、owner/repo/item）。
预设代码或命名预设来自 ui.shadcn.com 的带版本前缀的 base62 字符串（例如 a2r6bw），或用于 init 或 apply 的命名预设（nova、vega、maia、lyra、mira、luma）。

03 Skill 内部

shadcn Skill 赋予 Claude Code 和 Codex 的规则

SKILL.md 为 Agent 设定的 8 条具体指令、默认值与限制——文件中真正改变结果的部分。

使用 gap-，永远不要使用 space-x- 或 space-y-*
对于 flex 子元素之间的间距，使用 gap-。对于垂直堆叠，使用 flex flex-col gap-。永远不允许使用 space-x- 和 space-y-。
表单使用 FieldGroup + Field
表单布局必须使用 FieldGroup 和 Field 组件。永远不要用带 space-y- 或 grid gap- 的原始 div 来做表单布局。
Button 中的图标使用 data-icon
Button 内部的图标必须带有 data-icon="inline-start" 或 data-icon="inline-end"。组件内部的图标不允许使用 size-4 或 w-4 h-4 之类的尺寸类。
Item 始终位于其 Group 内部
SelectItem 应位于 SelectGroup 内部，DropdownMenuItem 应位于 DropdownMenuGroup 内部，CommandItem 应位于 CommandGroup 内部。永远不要直接渲染 item。
使用语义化颜色 token，而非原始数值
使用 bg-primary、text-muted-foreground 等。永远不要使用原始的 Tailwind 颜色，如 bg-blue-500 或 text-emerald-600。不允许手动覆盖 dark: 颜色。
Dialog、Sheet 和 Drawer 始终需要一个 Title
为了可访问性，DialogTitle、SheetTitle 和 DrawerTitle 是必需的。如果标题需要在视觉上隐藏，请使用 className="sr-only"。
永远不要手动解码预设代码
使用 npx shadcn@latest preset decode <code>、preset url <code>，或 preset open <code>。对于项目感知的 preset 检测，使用 preset resolve。切勿手动拼接 preset URL。
使用项目的包运行器执行所有 CLI 命令
根据项目的 packageManager 字段，使用 npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。如果项目使用 pnpm 或 bun，切勿硬编码 npx。

04 投入使用

在 Claude Code 或 Codex 中安装 shadcn

一条 npx skills add 命令，然后在你的 Agent 中执行第一个任务和对结果的清单检查。

将 shadcn 添加到 Claude Code、Codex 或你的 Agent

在你的项目中运行；安装程序会询问要把它添加到哪个 Agent。

Terminal

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

用于 skills/shadcn/SKILL.md 的通用 skills CLI 形式；仓库可能会记录自己的路径。

给 Skill 一个首次 UI 设计任务

按 skill 自身的术语撰写；把括号中的部分换成你的内容。

Starter prompt

I need a settings page with tabs for profile, account, and notifications. Each tab should have form fields grouped by section, with a save button at the bottom. Use the project's existing shadcn components and follow the FieldGroup pattern. The profile tab needs an avatar upload, the account tab needs email and password inputs with inline buttons to change them, and the notifications tab needs toggle groups for frequency (daily, weekly, monthly) and a set of checkboxes for notification types. Make sure all validation states use data-invalid and aria-invalid correctly.

来源：依据 SKILL.md，按 skill 自身的术语撰写。

检查首次结果

SKILL.md 本身如何描述正确的结果：

运行 npx shadcn@latest info 以确认该组件已添加到已安装组件列表中
检查图标导入是否与项目的 iconLibrary 字段（lucide-react、@tabler/icons-react 等）一致

在 OpenDesign 中通过其 SKILL.md 链接导入 shadcn：Plugins → Add → Skill → Import from link，然后在顶部栏中选择它。

下载 OpenDesign 阅读快速入门

05 开源、可追溯

来源、许可与验证

本页面事实的来源，以及最后检查时间。

Author: shadcn
Repository: github.com/shadcn-ui/ui 分支 main
Skill 文件: skills/shadcn/SKILL.md 验证时记录的内容校验和；commit 2b3e6d4
License: MIT 来自 LICENSE.md。
仓库星标数: 123,708 GitHub 快照拍摄于 2026-09-14，针对整个 shadcn-ui/ui 仓库。不是 shadcn 的评分或使用计数。
已由 OpenDesign 验证: 2026-09-14 已检查源文件、路径、许可文本和 star 数量。未内置在 OpenDesign 主程序（检查日期 2026-08-28）；本页面未记录实际运行。

SKILL.md 内部

当前项目上下文从 npx shadcn@latest info --json 注入实时项目配置和已安装组件
原则优先使用现有组件，组合而非重新发明，使用内置变体，使用语义化颜色
关键规则针对样式、表单、组合、图标、聊天和 CLI 的强制规则，并附有详细文件链接
关键模式最常见的代码模式：表单布局、验证、按钮中的图标、间距、等宽高、状态颜色
组件选择将 UI 需求映射到正确的 shadcn 组件（按钮、表单、覆盖层、反馈、导航、聊天）的对照表
关键字段解释来自项目上下文的 aliases、isRSC、tailwindVersion、base、iconLibrary、resolvedPaths、framework、packageManager、preset
组件文档、示例与用法运行 npx shadcn@latest docs 获取 URL，抓取它们以获得正确的 API 和使用模式
工作流九步流程：获取上下文、检查是否已安装、搜索、获取文档、安装、修复导入、审查、处理 registry、切换 preset
更新组件使用 --dry-run 和 --diff 合并上游变更，同时保留本地修改，未经批准切勿使用 --overwrite
快速参考init、apply、add、search、docs、view、preset 操作的 CLI 命令示例，附带标志和 registry 语法
详细参考指向表单、组合、聊天、图标、样式、base-vs-radix、CLI、registry、定制等独立规则文件的链接

Skill 自身的描述

"管理 shadcn 组件和项目——添加、搜索、修复、调试、样式设置和组合 UI，包括聊天界面。提供项目上下文、组件文档和使用示例。适用于使用 shadcn/ui、组件注册表、预设、--preset 代码或任何包含 components.json 文件的项目。也适用于"shadcn init"、"使用 --preset 创建应用"或"切换到 --preset"。"

SKILL.md 的 front-matter 描述。完整文件约 19,427 字符。在 GitHub 上阅读完整文件。

shadcn

在真实 UI 设计任务上运行 shadcn。

下载 OpenDesign，从其 SKILL.md 链接导入 shadcn，粘贴上方的提示词，在查看结果前先阅读计划。

下载 OpenDesign 浏览所有 skills

终端

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

shadcn Skill 在 Claude Code 和 Codex 中的作用

以 skill 自身的术语

工作方式

何时使用 shadcn Skill

适合场景

了解边界

需要提供的信息

shadcn Skill 赋予 Claude Code 和 Codex 的规则

使用 gap-，永远不要使用 space-x- 或 space-y-*

表单使用 FieldGroup + Field

Button 中的图标使用 data-icon

Item 始终位于其 Group 内部

使用语义化颜色 token，而非原始数值

Dialog、Sheet 和 Drawer 始终需要一个 Title

永远不要手动解码预设代码

使用项目的包运行器执行所有 CLI 命令