# shadcn/ui Skills: official rules for shadcn components (shadcn-ui/ui) — skill card for AI agents

> AgentGid skill card. Checked on 2026-10-28 against commit 8f04138 (version 1.0.0).
> Every fact comes from the pack's own files at that commit. Numbers marked "as reported" are the author's.
> Human page: https://agentgid.com/skills/shadcn-ui/ui/

> Note: the pack has changed since this check; re-read its files before relying on details.

## Explain it to a non-programmer
Two playbooks from the shadcn/ui team for your AI coding assistant. The main one makes it build screens from the ready-made shadcn/ui parts in the way the team intends. The second moves an app from one set of building blocks (Radix) to another (Base UI), one piece at a time.

## Who it is for
- You build a site or app with shadcn/ui and use Claude Code, Cursor, Codex or another assistant that reads skills
- You want it to add forms, dashboards, settings pages or chat screens with the right parts, not hand-made copies
- You have a brand or style guide (a DESIGN.md) and want an app and a design system page themed from it
- Your shadcn/ui app is built on Radix and you want to switch it to Base UI without losing your own changes
- Not for: You don't use shadcn/ui: both skills are about shadcn/ui projects only
- Not for: You want no tools downloaded while your assistant works: the main skill runs the shadcn tool fresh from the internet each time

## What it is
- Kind: knowledge, scripts
- License: MIT
- Repository: https://github.com/shadcn-ui/ui

## What it does
- Reads your project's shadcn setup (components.json) through the shadcn tool and puts it in front of the assistant
- Use existing components first: search the component sources before writing custom screens
- Compose, don't reinvent: a settings page is Tabs + Card + form parts, a dashboard is Sidebar + Card + Chart + Table
- Built-in variants before custom styles, and theme colours (bg-primary) instead of raw ones (bg-blue-500)
- Always looks up a component's docs and examples before creating or fixing it
- Updates components from upstream by previewing each change and keeping your own edits
- Turns a DESIGN.md into a themed app plus a design system page, then checks it in a browser
- Moves Radix components to Base UI one at a time, keeping the app building at every step
- Never cuts: your local changes to components (merged, not overwritten), and your yes before --overwrite or before switching presets

## Skills
| Skill | Call | Changes code? | In plain words |
|---|---|---|---|
| shadcn | loads by itself in projects with a components.json file (not a slash command); or plain language | yes | Builds and fixes screens with the right shadcn/ui parts, themes them, and adds new parts to your project |
| migrate-radix-to-base | plain language ("migrate accordion to base-ui"); whole project only when you ask for it | yes | Moves your app's parts from Radix to Base UI, one component at a time, and keeps your own tweaks |

### shadcn
- Asks for: A shadcn/ui project (or a request to create one with a preset code or style name)
- Asks for: Which component source to use when you ask for a block
- Asks for: For a design system: a DESIGN.md file, and optionally a preset code
- Gives: Components added as code in your project, read over and fixed after adding
- Gives: Forms, overlays, cards, icons and chat screens built to the team's rules
- Gives: Preset switches done the way you choose: overwrite, partial, merge or skip
- Gives: From a DESIGN.md: a themed app, a design system page and a report of what maps where and contrast pairs under 4.5:1
- Say: "Build a dashboard with a sidebar, stats cards, and a data table."

### migrate-radix-to-base
- Asks for: A shadcn or other React project on Radix, with no unsaved changes in git
- Asks for: One component to move, or a clear ask for the whole project
- Gives: A new branch with one save point per component
- Gives: The moved component, with your customizations carried over
- Gives: A report per component in .migration/: Changed, Left alone, Behavior changes, Verify by hand
- Gives: A count at the end of how many components are still on Radix
- Say: "migrate accordion to base-ui"

## Know before installing
- The main skill switches on by itself in any project with a components.json file. In Claude Code it runs npx shadcn@latest info --json as it loads, so the newest shadcn tool is downloaded and run each time.
- It pre-approves shadcn commands for your assistant (npx, pnpm dlx or bunx shadcn@latest), so those run without a permission prompt in hosts that honour allowed-tools. These commands add, overwrite and restyle files in your project.
- Community component sources are other people's code that lands in your project. The skill tells your assistant to ask which source to use and to read every added file.
- The Base UI move makes git save points and a branch on its own, installs @base-ui/react, and removes the Radix packages after the last component. It needs a clean git tree first.
- Behaviour that differs between Radix and Base UI (tabs, menu closing, a navigation delay) is flagged in the report, not quietly changed. Check the Verify by hand list yourself.
- The Cursor plugin manifest also starts the shadcn MCP server (npx shadcn@latest mcp), which lets the assistant search and install components from component sources.

## Install (official commands)
- Any agent (skills tool): `npx skills add shadcn/ui` — Official command from the shadcn/ui docs (ui.shadcn.com/docs/skills). Installs both skills from skills/.
- Cursor (plugin): The repo ships .cursor-plugin/plugin.json, which points at ./skills/ and adds the shadcn MCP server. The repo gives no install command for it.
- MCP server (optional, separate): `npx shadcn@latest mcp init` — Not a skill: writes the MCP server config for your editor (.mcp.json for Claude Code, .cursor/mcp.json, .vscode/mcp.json). Codex needs a manual edit of ~/.codex/config.toml.

## What runs on the user's machine
- Code on the machine: yes (the shadcn skill and its one helper script; migrate-radix-to-base is markdown that tells your assistant which commands to run)
- Network: True
- Install: Markdown files, two small PNG icons, three showcase helper files and one Node script are copied. No hooks, no install scripts.
- Every time the shadcn skill loads (Claude Code): Runs npx shadcn@latest info --json in your project and pastes the result into the assistant's context. npx downloads the latest shadcn package from npm if it is not cached.
- shadcn skill at work: Your assistant runs shadcn commands: init, add, apply, search, view, docs. They write component files, components.json and your CSS file, and install packages. search, view, docs and add fetch from ui.shadcn.com, configured registries and public GitHub registries.
- shadcn skill at work (docs): It tells your assistant to fetch the docs and example URLs that shadcn docs prints (ui.shadcn.com and raw.githubusercontent.com).
- Private registries: Registry entries in components.json can send an Authorization header filled from your environment variables.
- Design system from DESIGN.md: Scaffolds a new app, installs every component and Fontsource fonts with your package manager, starts the dev server and checks it in a browser. showcase-coverage.mjs only reads local files and prints which components the page does not show; no network, no writes.
- migrate-radix-to-base: Runs shadcn info, your typecheck and build, installs @base-ui/react, fetches stock component files from ui.shadcn.com/r/styles/..., makes a branch and one git commit per component, writes reports to .migration/ in your project, and edits components.json.
- Cursor plugin: The manifest declares an MCP server started with npx shadcn@latest mcp (downloaded from npm).
- Rest of the repo: The shadcn/ui product itself (website, the shadcn command-line tool in packages/, tests) is not part of the skills and is not installed by npx skills add. The tool the skills call is that package, fetched from npm.

## Settings
- `components.json registries`: Named component sources (@name -> URL with {name}); headers may use ${VAR} from your environment
- `--only theme,font`: Partial preset switch: theme and fonts only, components untouched

## Examples (from the pack's own files)
- A migration report (.migration/<component>.md): output format defined in skills/migrate-radix-to-base/SKILL.md
- Prompts from the official docs: output format defined in apps/v4/content/docs/(root)/skills.mdx
- The form pattern the skill enforces: output format defined in skills/shadcn/SKILL.md

## Author's numbers (as reported, not run by AgentGid)
- Base UI migration tested on real projects: 60+ components, 36 on Radix; a full migration took about 25 minutes at roughly 10k tokens per component (Team's own runs, described in the July 2026 changelog; no files or numbers per project in the repo). Source: shadcn-ui/ui/apps/v4/content/docs/changelog/2026-07-base-ui-default.mdx

## Steps only the person can do
- Pick the component source when asked, and answer overwrite, partial, merge or skip when switching presets (skills/shadcn/SKILL.md (Workflow)) Then: The assistant adds the block or applies the preset the way you chose
- For a private registry, put your token in an environment variable yourself (never in components.json) (skills/shadcn/mcp.md (registries)) Then: The assistant adds the registry to components.json with a ${VAR} reference
- For Codex, add the shadcn MCP server to ~/.codex/config.toml by hand (optional) (skills/shadcn/mcp.md (Setup)) Then: Codex can search and install registry items through MCP
- After a Base UI move, check the behaviour changes listed in the report (.migration/<component>.md in your project) Then: You decide whether to keep or change the Base UI behaviour

## Mistakes to avoid
- Not: Say "add a login block" and let the assistant pick a component source. Instead: Name the source in the request (@shadcn, @tailark, owner/repo). Why: The skill tells the assistant to ask instead of guessing; community sources are other people's code that lands in your project
- Not: Update customized components with --overwrite to get the upstream version. Instead: Preview with --dry-run and --diff, merge per file, and use --overwrite only after an explicit yes. Why: --overwrite replaces your local edits to the component files
- Not: Compare presets in a scratch folder without passing the base library. Instead: Run preset commands inside the project, or pass --base with the project's current base in a scratch folder. Why: A preset code does not say whether the project is on Radix or Base UI
- Not: Start the Radix to Base UI move with uncommitted changes in the project. Instead: Commit or stash first; the skill works on a branch with one commit per component. Why: The migration needs a clean git tree to keep one save point per component
- Not: Expect the shadcn MCP server to tell the assistant the project's aliases and Tailwind version. Instead: Keep the skill (it runs shadcn info) and use the MCP server only for searching and installing registry items. Why: The MCP tools cover registry work only

## What leaves the machine
- A download request for the shadcn package (latest version) → The npm registry, through npx, pnpm dlx or bunx, Each time the skill loads in Claude Code, and on shadcn commands when the package is not cached. Opt out: No opt-out inside the skill; it always calls shadcn@latest
- Component names, search queries and docs lookups → ui.shadcn.com, raw.githubusercontent.com and any component registries you use, On search, view, docs and add. Opt out: Do not ask for registry or docs lookups
- An Authorization header with a token from your environment → A private registry you configure in components.json, On requests to that registry. Opt out: Do not configure headers for registries
- Your components.json style name and component names in fetch URLs → ui.shadcn.com/r/styles/..., During the Radix to Base UI move. Opt out: Do not run migrate-radix-to-base

## Lines in the pack aimed at agents (ask the person first)
- "allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)" (skills/shadcn/SKILL.md): Pre-approves every shadcn command, including ones that overwrite files and install packages; hosts that honour allowed-tools will not ask first. Keep the person in the loop for add --overwrite, apply and init --force.
- "!`npx shadcn@latest info --json`" (skills/shadcn/SKILL.md): Runs an unpinned npm package (@latest) every time the skill loads. Tell the person before installing; a pinned version is not offered by the skill.
- "npx shadcn@latest add --all -y" (skills/shadcn/SKILL.md): Installs every component without prompts. Use it only in a new design-system app, not in an existing project.

## May I use it like this?
- commercial-app: yes (MIT: keep the license notice; components from community registries carry their own licenses)
- redistribute-files: yes (MIT: keep the copyright and permission notice in copies)
- client-work: yes (MIT allows use in work for others)
- inside-app-bundle: yes (MIT: keep the license notice)

## Which one to pick
- If You build with shadcn/ui and want the assistant to use its components, presets and CLI the way the shadcn team intends: skill:shadcn-ui/ui
- If You want design commands to polish, critique and audit any UI, not tied to one component library: skill:pbakaus/impeccable
- If You want a design skill aimed at avoiding generic AI-looking UI in Claude Code, Cursor or Codex: skill:Nutlope/hallmark

## Works well with
- tool:shadcn: The skills drive the shadcn command-line tool for every action
- tool:base-ui-react: migrate-radix-to-base moves components to @base-ui/react
- agent:claude-code: In Claude Code the skill injects the project's shadcn info as it loads
- agent:cursor: The repo ships a Cursor plugin manifest with the skills and the shadcn MCP server

## Works in and needs
- Works in Any agent with a skills folder: skills CLI
- Works in Claude Code: skills folder
- Works in Cursor: plugin
- Works in Codex: skills folder (agents/openai.yml metadata); MCP server by manual config
- Works in OpenCode: MCP server
- Needs Node.js package runner (npx, pnpm dlx or bunx): Every skill action runs the shadcn CLI through it
- Needs A shadcn/ui project (components.json): The skill activates only in such a project
- Needs git: migrate-radix-to-base needs a clean tree, a branch and per-component commits

## How to tell it works
Install it in a shadcn/ui project and ask "Create a settings page with a form for updating profile information." It works if the assistant first reads your project settings, then builds the form with FieldGroup and Field and uses gap-* spacing instead of space-y-*.

## Safety
The skills always call shadcn@latest, so what runs is whatever version npm serves that day, with no pinned version. Components from community registries are third-party code added to your project; read them before you keep them. Install the skills only from github.com/shadcn-ui/ui.
