From b9b30a23e644c952fbe52db337bfdd427bc6449f Mon Sep 17 00:00:00 2001 From: shadcn Date: Thu, 26 Feb 2026 22:17:32 +0400 Subject: [PATCH] feat: add shadcn skills --- .changeset/forty-lions-repair.md | 5 + skills/shadcn/SKILL.md | 128 +++++++++ skills/shadcn/agents/openai.yml | 5 + skills/shadcn/assets/shadcn-small.png | Bin 0 -> 1049 bytes skills/shadcn/assets/shadcn.png | Bin 0 -> 3852 bytes skills/shadcn/cli.md | 229 +++++++++++++++ skills/shadcn/customization.md | 180 ++++++++++++ skills/shadcn/mcp.md | 94 +++++++ skills/shadcn/patterns.md | 230 +++++++++++++++ skills/shadcn/registry-authoring.md | 387 ++++++++++++++++++++++++++ 10 files changed, 1258 insertions(+) create mode 100644 .changeset/forty-lions-repair.md create mode 100644 skills/shadcn/SKILL.md create mode 100644 skills/shadcn/agents/openai.yml create mode 100644 skills/shadcn/assets/shadcn-small.png create mode 100644 skills/shadcn/assets/shadcn.png create mode 100644 skills/shadcn/cli.md create mode 100644 skills/shadcn/customization.md create mode 100644 skills/shadcn/mcp.md create mode 100644 skills/shadcn/patterns.md create mode 100644 skills/shadcn/registry-authoring.md diff --git a/.changeset/forty-lions-repair.md b/.changeset/forty-lions-repair.md new file mode 100644 index 0000000000..9cc315e949 --- /dev/null +++ b/.changeset/forty-lions-repair.md @@ -0,0 +1,5 @@ +--- +"shadcn": minor +--- + +add shadcn/skills diff --git a/skills/shadcn/SKILL.md b/skills/shadcn/SKILL.md new file mode 100644 index 0000000000..d52fb8d8ff --- /dev/null +++ b/skills/shadcn/SKILL.md @@ -0,0 +1,128 @@ +--- +name: shadcn +description: Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI. 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". +user-invocable: false +--- + +# shadcn/ui + +Copy-paste component library. Components are added as source code to the user's project via the CLI or MCP tools. + +> **IMPORTANT:** Always use the `shadcn` command directly. Never prefix with `npx`, `pnpm dlx`, or any package runner. + +## Current Project Context + +```json +!`shadcn info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'` +``` + +The JSON above contains the project config and installed components. Use `shadcn docs ` to get documentation and example URLs for any component. + +## Principles + +1. **Use existing components first.** Check registries via MCP or `shadcn search` before writing custom UI. Check community registries too. +2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table. +3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc. +4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`. + +## Critical Rules + +These rules are **always enforced**. See [patterns.md](./patterns.md) for full examples. + +1. **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout. +2. **Items always inside their Group.** `SelectItem`/`SelectLabel` → `SelectGroup`. `DropdownMenuItem`/`DropdownMenuLabel`/`DropdownMenuSub` → `DropdownMenuGroup`. `MenubarItem` → `MenubarGroup`. `ContextMenuItem` → `ContextMenuGroup`. `CommandItem` → `CommandGroup`. +3. **Icons in `Button` use `data-icon`.** Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix). No sizing classes on the icon. +4. **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never use raw `Input` or `Textarea` inside an `InputGroup`. +5. **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` components with manual active state. +6. **Callouts use `Alert`.** Don't build custom styled `div` containers for info/warning messages. +7. **Empty states use `Empty`.** Don't build custom empty state markup. +8. **Use existing components before custom markup.** Check if a component exists before writing a styled `div`. +9. **`className` for layout, not styling.** Add layout utilities (`w-full`, `grid`, `flex`, `gap-*`) but never override component colors or typography. +10. **Use `asChild` (radix) or `render` (base) for custom triggers.** Don't wrap triggers in extra elements. Check the `base` field from `shadcn info` to determine which prop to use. +11. **Toast via `sonner`.** Use `toast()` from `sonner`. Don't build custom toast/notification markup. +12. **Pass icons as objects, not string keys.** Use `icon={CheckIcon}`, not a string key to a lookup map. +13. **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.** Never place a `Button` directly inside or adjacent to an `Input` with custom positioning. Wrap in `InputGroup` and use `InputGroupAddon` for the button. + +## Key Fields + +The injected project context contains these key fields: + +- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode. +- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"`. +- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`. +- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one. +- **`style`** → component visual treatment (e.g. `nova`, `vega`). +- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props. +- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`. +- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc. +- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA). +- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`). + +See [cli.md — `info` command](./cli.md) for the full field reference. + +## Component Docs, Examples, and Usage + +Run `shadcn docs ` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content. + +```bash +shadcn docs button dialog select +``` + +**When creating, fixing, debugging, or using a component, always run `shadcn docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing. + +## Workflow + +1. **Get project context** — already injected above. Run `shadcn info` again if you need to refresh. +2. **Check installed components** — look in the `resolvedPaths.ui` directory before importing or adding. Don't import components that haven't been added, and don't re-add ones already installed. +3. **Find components** — MCP `shadcn:search_items_in_registries` or `shadcn search`. +4. **Get docs and examples** — run `shadcn docs ` to get URLs, then fetch them. Alternatively use MCP `shadcn:view_items_in_registries` or `shadcn view`. +5. **Install** — MCP `shadcn:get_add_command_for_items` or `shadcn add`. +6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `shadcn info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project. +7. **Verify** — MCP `shadcn:get_audit_checklist`. + +8. **Switching presets** — Before running `shadcn init --preset ` in an existing project, always ask the user if they'd like to reinstall existing UI components. If yes, use the `--reinstall` flag to overwrite them with the new preset styles. + +If MCP is unavailable, use CLI: `shadcn search`, `shadcn view`, `shadcn add`. + +## Quick Reference + +```bash +# Create a new project. +shadcn init --name my-app --preset base-nova +shadcn init --name my-app --preset a2r6bw --template vite + +# Create a monorepo project. +shadcn init --name my-app --preset base-nova --monorepo +shadcn init --name my-app --preset base-nova --template next --monorepo + +# Initialize existing project. +shadcn init --preset base-nova +shadcn init --defaults # shortcut: --template=next --preset=base-nova + +# Add components. +shadcn add button card dialog +shadcn add @magicui/shimmer-button +shadcn add --all + +# Search registries. +shadcn search @shadcn -q "sidebar" +shadcn search @blocks -q "stats" + +# Get component docs and example URLs. +shadcn docs button dialog select + +# View item details. +shadcn view @shadcn/button +``` + +**Named presets:** `base-nova`, `radix-nova` +**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) +**Preset codes:** Base62 strings starting with `a` (e.g. `a2r6bw`), from [ui.shadcn.com](https://ui.shadcn.com). + +## Detailed References + +- [cli.md](./cli.md) — Commands, flags, presets, templates +- [mcp.md](./mcp.md) — MCP server setup, tools, registry configuration +- [patterns.md](./patterns.md) — UI patterns and component composition rules +- [customization.md](./customization.md) — Theming, CSS variables, extending components +- [registry-authoring.md](./registry-authoring.md) — Building and publishing custom registries diff --git a/skills/shadcn/agents/openai.yml b/skills/shadcn/agents/openai.yml new file mode 100644 index 0000000000..ab636da86b --- /dev/null +++ b/skills/shadcn/agents/openai.yml @@ -0,0 +1,5 @@ +interface: + display_name: "shadcn/ui" + short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI." + icon_small: "./assets/shadcn-small.png" + icon_large: "./assets/shadcn.png" diff --git a/skills/shadcn/assets/shadcn-small.png b/skills/shadcn/assets/shadcn-small.png new file mode 100644 index 0000000000000000000000000000000000000000..547154b97f2298335159c23eec1dac0d147a1246 GIT binary patch literal 1049 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`Ea{HEjtmSN`?>!lvI6-E$sR$z z3=CCj3=9n|3=F@3LJcn%7)lKo7+xhXFj&oCU=S~uvn$XBDAAG{;hE;^%b*2hb1<+n z3NbJPS&Tr)z$nE4G7ZRL@M4sPvx68lplX;H7}_%#SfFa6fHVkr05M1pgl1mAh%j*h z6I`{x0%imor0saV%ts)_S>O>_%)r1c48n{Iv*t(uO^eJ7i71Ki^|4CM&(%vz$xlkv ztH>0+>{umUo3Q%e#RDspr3imfVamB1>jfNYSkzLEl1NlCV?QiN}Sf^&XRs)CuG zfu4bq9hZWFf=y9MnpKdC8&o@xXRDM^Qc_^0uU}qXu2*iXmtT~wZ)j<0sc&GUZ)Btk zRH0j3nOBlnp_^B%3^4>|j!SBBa#3bMNoIbY0?6FNr2NtnTO}osMQ{LdXGvxn!lt}p zsJDO~)CbAv8|oS8!_5Y2wE>A*`4?rT0&NDFZ)a!&R*518wZ}#uWI2*!AU*|)0=;U- zWup%dHajlKxQFb(K%V94;uvBfm>Yb$>yU#$kCbgiC(9RwrlwA(rsW(``(6H=zq@!* zUB_~Trk_lTdxPh$yxDTsVY&L;b+6{tRm^+d+gl^OQcCIBok=%y)Vhx@dR1ceL3r{0 z9=2nMXx8DxEkhL{v?(>~8{qDBkfB!u-iDB`| z-5d%Ae82YI%n8Zg9$mRN?o-|V)V*=5b-R>a>}P2{=pcK^B(&B-W{C#Z!Q%b*ueK>n zK6ymYLRneebCKDSzcqHEHFopo-mkH{zIkt2Z0^086Tko7%N)NxoZYSDM1jSUwPpuS zSeq*wzrC2D(tq4pZ#s9QP@Cd8Q^wW3*2cL_519?*;#4`B;+ei#o;C{Kkamm3Jooa; zE$3K-+c(6ShTjelW_B*W5o zcS6z34IR5C-SIF8m(lui^IOy!-~We?b1?PSGniCYR=ZyR^%<1lJzf1=);T3K0RU@N BSy=!8 literal 0 HcmV?d00001 diff --git a/skills/shadcn/assets/shadcn.png b/skills/shadcn/assets/shadcn.png new file mode 100644 index 0000000000000000000000000000000000000000..b7b6814acc25073e5f48099b1fd3f70c47bfb1c3 GIT binary patch literal 3852 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. Configuration is read from `components.json`. + +> **IMPORTANT:** Always use the `shadcn` command directly. Never prefix with `npx`, `pnpm dlx`, or any package runner. + +--- + +## Commands + +### `init` — Initialize or create a project + +```bash +shadcn init [components...] [options] +``` + +Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step. + +| Flag | Short | Description | Default | +|------|-------|-------------|---------| +| `--template