Geruyang/agent-skills-library

导出副本边界与技能别名

迁移、安装、修复和经验回写只作用于当前加载的目标宿主技能副本。原 Codex 技能/MCP、下载的源码和 original-skills 均为来源材料，不因执行本副本而写入；只有用户另行明确要求配置 Codex 产品本身时，才按该产品流程处理指定目标。脚本需要安装目录或状态目录时，显式提供目标路径；不得从 CODEX_HOME 隐式推断写入位置。

跨技能名称可能沿用源库别名。先查 技能别名表，优先选择同来源、同插件的条目，再使用其 id 调用或读取对应入口；不得假定旧 $skill、superpowers:skill 名称在新宿主直接注册。不能确定目标时先核对，不替换真实产品命令或 Shell 环境变量。

跨宿主使用约定

本副本供支持 Agent Skills 的客户端使用。先检查当前宿主实际提供的工具、权限和已连接服务，再执行正文工作流。原文中的宿主工具标识是能力参考；只有实际发现该工具时才可调用，其他宿主应使用经核验的等价 MCP、CLI 或 API。没有等价能力的步骤必须报告不可用，不能虚构调用或完成状态。

技能资源以本技能目录为基准；输出写入当前项目中用户指定的位置。通过技能名称或自然语言触发，具体快捷命令由宿主决定。涉及真实产品、模型 API、协议字段和官方网址的名称保持原意。授权、审批、隐私和工具范围限制在迁移后仍然有效；不得为兼容而扩大权限。具体依赖与迁移说明见同目录 PORTABILITY.md。

shadcn/ui

用于构建 UI、组件和设计系统的框架。组件通过 CLI 以源代码形式添加到用户项目中。

重要： 使用项目的包管理器运行所有 CLI 命令：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest——基于项目的 packageManager。以下示例使用 npx shadcn@latest，但请根据项目替换为正确的运行器。

当前项目上下文

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

上述 JSON 包含项目配置和已安装的组件。使用 npx shadcn@latest docs <component> 获取任意组件的文档和示例 URL。

原则

1. 优先使用现有组件。 在编写自定义 UI 之前，使用 npx shadcn@latest search 检查注册表。同时也要检查社区注册表。
2. 组合，而非重新发明。 设置页面 = Tabs + Card + 表单控件。仪表盘 = Sidebar + Card + Chart + Table。
3. 优先使用内置变体，再考虑自定义样式。 例如 variant="outline"、size="sm" 等。
4. 使用语义化颜色。 例如 bg-primary、text-muted-foreground——切勿使用像 bg-blue-500 这样的原始值。

关键规则

以下规则始终强制执行。每条规则都链接到一个包含错误/正确代码对的文件。

样式与 Tailwind → styling.md

• className 用于布局，而非样式。 切勿覆盖组件颜色或排版。
• 禁止使用 space-x-* 或 space-y-*。 使用 flex 配合 gap-*。对于垂直堆叠，使用 flex flex-col gap-*。
• 当宽度和高度相等时，使用 size-*。 例如 size-10 而非 w-10 h-10。
• 使用 truncate 简写。 而非 overflow-hidden text-ellipsis whitespace-nowrap。
• 禁止手动 dark: 颜色覆盖。 使用语义化 token（如 bg-background、text-muted-foreground）。
• 使用 cn() 处理条件类名。 不要编写手动的模板字面量三元表达式。
• 覆盖层组件上禁止手动设置 z-index。 Dialog、Sheet、Popover 等组件会自行处理堆叠。

表单与输入 → forms.md

• 表单使用 FieldGroup + Field。 切勿使用原始的 div 搭配 space-y-* 或 grid gap-* 进行表单布局。
• InputGroup 使用 InputGroupInput/InputGroupTextarea。 InputGroup 内部切勿使用原始的 Input/Textarea。
• 输入框内的按钮使用 InputGroup + InputGroupAddon。
• 选项集（2–7 个选项）使用 ToggleGroup。 不要循环 Button 并手动管理激活状态。
• 使用 FieldSet + FieldLegend 对相关的复选框/单选按钮进行分组。 不要使用带标题的 div。
• 字段验证使用 data-invalid + aria-invalid。 data-invalid 放在 Field 上，aria-invalid 放在控件上。对于禁用状态：data-disabled 放在 Field 上，disabled 放在控件上。

组件结构 → composition.md

• 项目总是位于其组内。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• 使用 asChild（radix）或 render（base）处理自定义触发器。 从 npx shadcn@latest info 检查 base 字段。 → base-vs-radix.md
• Dialog、Sheet 和 Drawer 始终需要 Title。 DialogTitle、SheetTitle、DrawerTitle 是辅助功能必需的。如果视觉上隐藏，使用 className="sr-only"。
• 使用完整的 Card 组合。 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要把所有内容都放在 CardContent 里。
• Button 没有 isPending/isLoading 属性。 使用 Spinner + data-icon + disabled 进行组合。
• TabsTrigger 必须位于 TabsList 内部。 切勿直接在 Tabs 中渲染触发器。
• Avatar 总是需要 AvatarFallback。 用于图片加载失败的情况。

使用组件，而非自定义标记 → composition.md

• 优先使用现有组件，再考虑自定义标记。 在编写带样式的 div 之前，检查是否存在相应组件。
• 标注使用 Alert。 不要构建自定义样式 div。
• 空状态使用 Empty。 不要构建自定义空状态标记。
• Toast 通过 sonner 实现。 使用 sonner 的 toast() 方法。
• 使用 Separator 替代 <hr> 或 <div className="border-t">。
• 使用 Skeleton 作为加载占位符。不要使用自定义的 animate-pulse div。
• 使用 Badge 替代自定义样式的 span。

图标 → icons.md

• Button 中的图标使用 data-icon。 在图标上使用 data-icon="inline-start" 或 data-icon="inline-end"。
• 组件内部的图标记请不要使用尺寸类。 组件通过 CSS 处理图标大小。不使用 size-4 或 w-4 h-4。
• 将图标作为对象传递，而非字符串键。 使用 icon={CheckIcon}，而不是字符串查找。

CLI

• 切勿手动解码或获取预设代码。 直接将它们传递给 npx shadcn@latest init --preset <code>。

关键模式

以下是最常见的模式，用于区分正确的 shadcn/ui 代码。对于边界情况，请参阅上面链接的规则文件。

// 表单布局：FieldGroup + Field，而非 div + Label。
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// 验证：data-invalid 放在 Field 上，aria-invalid 放在控件上。
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// 按钮中的图标：data-icon，没有尺寸类。
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// 间距：gap-*，而非 space-y-*。
<div className="flex flex-col gap-4">  // 正确
<div className="space-y-4">           // 错误

// 相等尺寸：size-*，而非 w-* h-*。
<Avatar className="size-10">   // 正确
<Avatar className="w-10 h-10"> // 错误

// 状态颜色：Badge 变体或语义化 token，而非原始颜色。
<Badge variant="secondary">+20.1%</Badge>    // 正确
<span className="text-emerald-600">+20.1%</span> // 错误

组件选择

需求	使用
按钮/操作	Button，配合适当的变体
表单输入	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
在 2–5 个选项间切换	ToggleGroup + ToggleGroupItem
数据显示	Table、Card、Badge、Avatar
导航	Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination
覆盖层	Dialog（模态框）、Sheet（侧面板）、Drawer（底部抽屉）、AlertDialog（确认框）
反馈	sonner（toast）、Alert、Progress、Skeleton、Spinner
命令面板	Dialog 内部的 Command
图表	Chart（包装 Recharts）
布局	Card、Separator、Resizable、ScrollArea、Accordion、Collapsible
空状态	Empty
菜单	DropdownMenu、ContextMenu、Menubar
工具提示/信息	Tooltip、HoverCard、Popover

关键字段

注入的项目上下文包含以下关键字段：

• aliases → 为导入使用实际的别名前缀（例如 @/、~/），切勿硬编码。
• isRSC → 当为 true 时，使用 useState、useEffect、事件处理程序或浏览器 API 的组件需要在文件顶部添加 "use client"。在建议此指令时务必参考此字段。
• tailwindVersion → "v4" 使用 @theme inline 块；"v3" 使用 tailwind.config.js。
• tailwindCssFile → 定义自定义 CSS 变量的全局 CSS 文件。始终编辑此文件，切勿创建新文件。
• style → 组件视觉处理（例如 nova、vega）。
• base → 原始库（radix 或 base）。影响组件 API 和可用属性。
• iconLibrary → 决定图标导入。lucide 使用 lucide-react，tabler 使用 @tabler/icons-react 等。切勿假定为 lucide-react。
• resolvedPaths → 组件、工具函数、hooks 等的确切文件系统目标路径。
• framework → 路由和文件约定（例如 Next.js App Router 与 Vite SPA）。
• packageManager → 用于任何非 shadcn 依赖项的安装（例如 pnpm add date-fns 与 npm install date-fns）。

完整字段参考，请参见 cli.md — info 命令。

组件文档、示例和使用

运行 npx shadcn@latest docs <component> 获取组件文档、示例和 API 参考的 URL。获取这些 URL 以获取实际内容。

npx shadcn@latest docs button dialog select

在创建、修复、调试或使用组件时，始终先运行 npx shadcn@latest docs 并获取 URL。 这能确保您使用的是正确的 API 和使用模式，而不是猜测。

工作流

1. 获取项目上下文 — 已在上方注入。如果需要刷新，再次运行 npx shadcn@latest info。
2. 首先检查已安装的组件 — 在运行 add 之前，始终从项目上下文检查 components 列表或列出 resolvedPaths.ui 目录。不要导入尚未添加的组件，也不要重新添加已安装的组件。
3. 查找组件 — npx shadcn@latest search。
4. 获取文档和示例 — 运行 npx shadcn@latest docs <component> 获取 URL，然后获取它们。使用 npx shadcn@latest view 浏览尚未安装的注册表项目。要预览对已安装组件的更改，请使用 npx shadcn@latest add --diff。
5. 安装或更新 — npx shadcn@latest add。更新现有组件时，请先使用 --dry-run 和 --diff 预览更改（请参见下面的更新组件）。
6. 修复第三方组件中的导入路径 — 从社区注册表（例如 @bundui、@magicui）添加组件后，检查添加的非 UI 文件中是否有硬编码的导入路径，如 @/components/ui/...。这些路径可能不匹配项目的实际别名。使用 npx shadcn@latest info 获取正确的 ui 别名（例如 @workspace/ui/components）并相应地重写导入。CLI 会为其自己的 UI 文件重写导入，但第三方注册表组件可能使用与项目不匹配的默认路径。
7. 审查添加的组件 — 从任何注册表添加组件或块后，始终读取添加的文件并验证其正确性。检查是否缺少子组件（例如没有 SelectGroup 的 SelectItem）、缺少导入、不正确的组合或违反关键规则。同时，将所有图标导入替换为项目上下文中的 iconLibrary（例如，如果注册表项目使用 lucide-react 但项目使用 hugeicons，则交换导入和图标名称）。在继续之前修复所有问题。
8. 注册表必须明确指定 — 当用户要求添加块或组件时，不要猜测注册表。如果未指定注册表（例如用户说“添加一个登录块”而未指定 @shadcn、@tailark 等），询问使用哪个注册表。切勿代表用户默认为某个注册表。
9. 切换预设 — 首先询问用户：重新安装、合并还是跳过？
   • 重新安装：npx shadcn@latest init --preset <code> --force --reinstall。覆盖所有组件。
   • 合并：npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行 npx shadcn@latest info 列出已安装的组件，然后对每个已安装的组件使用 --dry-run 和 --diff 逐一进行智能合并。
   • 跳过：npx shadcn@latest init --preset <code> --force --no-reinstall。仅更新配置和 CSS，保持组件不变。
   • 重要：始终在用户的项目目录内运行预设命令。CLI 会自动保持 components.json 中的当前 base（base 与 radix）。如果必须使用 scratch/temp 目录（例如用于 --dry-run 比较），请显式传递 --base <current-base>——预设代码不编码 base。

更新组件

当用户要求从上游更新组件同时保留本地更改时，使用 --dry-run 和 --diff 进行智能合并。切勿直接获取原始文件并直接覆盖。

...

可用运行器和命令

• npx shadcn@latest
• pnpm dlx shadcn@latest
• bunx --bun shadcn@latest

使用 --help 查看完整命令列表。

依赖项

• shadcn/ui CLI
• 项目中的 React 和 Tailwind CSS（版本取决于项目配置）
• 图标库（如 lucide-react、@tabler/icons-react 等）
• 组件依赖项（如 recharts、sonner 等）会根据安装的组件自动添加。

迁移说明

请参阅同目录下的 PORTABILITY.md 了解详细的迁移说明。