Preface¶

The most common problem when using AI to write shadcn/ui code isn’t that it can’t create a Button component—it’s that the generated code doesn’t match your project setup. Aliases are written as @/components/ui while your actual repository uses @workspace/ui/components; icons default to lucide-react but your project has already switched to Tabler; forms use handwritten div + space-y-* while the official component combination uses FieldGroup + Field; the underlying primitives are Base UI, but the AI still uses Radix’s asChild. The components may run, but the styling, import paths, and APIs all follow a completely different set of conventions.

shadcn/ui itself is not a traditional npm component package, but rather writes source code directly into your project via its CLI. The official repository shadcn-ui/ui currently has over 120,000 stars, and components are generated based on your project’s components.json file. The CLI v4 released in March 2026 specifically added context support for coding assistants: the official Skill. Once installed, the assistant will first read your project configuration before deciding which registry to search, which components to install, and which combination rules to follow.

What This Is¶

One-sentence definition: shadcn is an Agent Skill maintained officially by shadcn/ui for managing component search, installation, repair, debugging, styling, and composition (including chat interfaces), and injecting real project configuration into projects that have a components.json file.

Source and attribution:
- Maintainer: shadcn-ui organization, code hosted in the official repository shadcn-ui/ui
- Directory: https://github.com/shadcn-ui/ui/tree/main/skills/shadcn
- Documentation: https://ui.shadcn.com/docs/skills
- The name field in SKILL.md is shadcn; user-invocable is set to false, meaning it is not a slash command and will load automatically when relevant tasks are detected.

The core problem it solves is very specific: instead of guessing component APIs based on training data, the assistant will first run shadcn info --json to retrieve the framework, Tailwind version, aliases, underlying primitive library (base / radix / aria), icon library, installed components, and resolved file paths, then generate code according to official rules.

Core Features¶

The official documentation divides the knowledge covered by the Skill into sections, which correspond directly to reference files in the repository.

1. Project Context. Every relevant interaction will execute shadcn info --json. SKILL.md emphasizes that these fields must follow the project setup and cannot be hardcoded:
- aliases: Import prefix, which could be @/, ~/, or a workspace path
- isRSC: When set to true, files using useState, useEffect, event handlers, or browser APIs need to add the "use client" directive
- tailwindVersion: v4 uses @theme inline, while v3 uses tailwind.config.js
- tailwindCssFile: Custom CSS variables should only be modified in this file, not create new ones separately
- base: Underlying primitive library, which determines the component API (for example, Radix uses asChild, while Base UI uses render)
- iconLibrary: Determines which package icons are imported from, do not default to lucide-react
- framework, packageManager, resolvedPaths: Routing conventions, dependency installation commands, and actual component file storage paths

2. CLI Usage. The Skill includes cli.md, which covers commands such as init, add, search, view, docs, info, apply, preset, and build, as well as flags like --dry-run, --diff, presets, and templates. CLI commands must follow the project’s package manager: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest.

3. Composition Rules. The rules/ directory contains Incorrect / Correct comparisons that enforce several common constraints:
- Forms should use FieldGroup + Field, not bare div with space-y-*
- Use ToggleGroup for 2–7 options, not handwritten custom Buttons with selected states
- Use flex + gap-* for spacing, not space-x-* / space-y-*
- Use semantic color tokens (bg-primary, text-muted-foreground) instead of hardcoded classes like bg-blue-500
- Dialog / Sheet / Drawer must have a Title; Avatar must include AvatarFallback
- Search for existing components before writing custom markup: use Alert for prompts, Empty for empty states, and Skeleton for loading states

4. Theming, Registry, and MCP. customization.md explains CSS variables, OKLCH, dark mode, and differences between Tailwind v3 and v4; registry.md explains how to write and publish custom registries; mcp.md explains the MCP server used to search, browse, and install entries from registries. The official note: registry operations use MCP, while project configuration still uses shadcn info, and there is no equivalent interface for MCP.

Installation and Activation¶

The official installation command provided in the documentation is:

pnpm dlx skills add shadcn/ui

The equivalent command on skills.sh is npx skills add shadcn/ui. This will install the Skill into the current project; afterwards, the assistant will load it automatically when working with shadcn/ui components. You can also specify a repository path:

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

skills is a universal installer maintained by Vercel Labs, supporting Claude Code, Cursor, Codex, OpenCode, and more. Project-level and user-level directories differ, with common examples listed below:

To install for a single specific tool, add the --agent flag, for example --agent cursor or --agent claude-code.

The Skill will load automatically only if the project contains a components.json file. This file is generated by the CLI’s init command and describes the framework, aliases, and registry. The official note: you do not need this file when copying and pasting components directly; you must have it if you want to use the CLI to add components to your project. Without this file, the Skill’s project detection will not activate, and the assistant will not be able to read the real project configuration.

You can initialize an existing project with:

pnpm dlx shadcn@latest init

If you also want to use natural language to search the registry and install blocks, you can additionally set up MCP. For Cursor, add this to your project’s .cursor/mcp.json:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

For Claude Code, add the same configuration to .mcp.json. You can also have the CLI generate the configuration automatically:

pnpm dlx shadcn@latest mcp init --client claude
pnpm dlx shadcn@latest mcp init --client cursor

Codex requires manual edits to ~/.codex/config.toml, as the CLI will not update this file automatically.

Typical Usage¶

The official documentation provides straightforward example prompts:
- Add a login form with email and password fields
- Create a settings page with a form for updating user profile information
- Build a Dashboard: sidebar, statistics cards, data table
- Switch to a specific --preset code
- Add a hero section from @tailark

The assistant should follow the prescribed workflow defined by the Skill internally, rather than writing JSX directly.

1. Read Project Configuration. This is done once at the start of the context; run again if a refresh is needed:

npx shadcn@latest info --json

2. Check Already Installed Components. Use the components list returned by info, or directly check the resolvedPaths.ui directory. Do not re-add components that are already in the project, and do not import files that have not been installed yet.

3. Search and Read Documentation. Before generating or modifying a component, retrieve its documentation and example URLs:

npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest docs button dialog select
npx shadcn@latest view @shadcn/button

4. Install or Update. When updating existing components, preview the changes first before deciding whether to overwrite them:

npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx

--overwrite must be explicitly approved. If the user says “update all”, you should first confirm the action.

5. Preset. Do not manually decode preset codes or construct URLs manually; use the CLI instead:

npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest apply a2r6bw --only theme,font
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset resolve

When switching presets, the Skill requires you to first confirm with the user: overwrite, partial update (theme / font), merge, or skip components and only modify configuration. apply only works for projects that already have a components.json file, and will preserve the current base setting.

Composition code should follow official examples, do not arbitrarily place Label and Input components inside a div:

<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

Validation states should be added to the correct nodes: data-invalid on Field, and aria-invalid on the control itself.

Applicable Scenarios and Notes¶

This Skill is suitable for these situations:
- You are already using shadcn/ui, or plan to run init to set up a new project, and want the assistant to generate code according to the repository’s aliases, icon library, and primitive library
- You need to install components, blocks from the official registry, community registries (such as @magicui, @tailark), or owner/repo
- You need to build pages like login forms, settings pages, Dashboards, or chat interfaces that require correct combination of multiple components
- You need to maintain a custom registry, or use MCP to search across multiple namespaces

There are several hard limits clearly stated in official materials:
1. Without components.json, the Skill will not work with the “current project”. You do not need this file when copying and pasting components, but the CLI and this Skill do.
2. Do not guess the registry if the user did not specify one. If the user only says “add a login block” without specifying @shadcn / @tailark / owner/repo, you should first ask which registry to use.
3. Import paths for third-party registries may be hardcoded. The CLI will modify its own UI files; community components may still use @/components/ui/.... After installation, you need to update the imports to match the real alias in info, and replace icons with the project’s configured iconLibrary.
4. Toast components follow the selected base library. Base UI projects use the toast export from the toast component; Radix and React Aria projects use sonner.
5. MCP cannot replace info. Searching components, viewing source code, and retrieving installation commands can use MCP tools; framework, aliases, and Tailwind version still need to be retrieved via the CLI’s info command.
6. Do not mix package managers for commands. The allowed Bash tools for the Skill are npx shadcn@latest *, pnpm dlx shadcn@latest *, and bunx --bun shadcn@latest *, following the packageManager field.

There is another migrate-radix-to-base Skill in the same repository for migrating from Radix to Base UI; the standard shadcn Skill covered in this article is used for daily component installation and page writing.

Summary¶

shadcn/ui places component source code directly into your project, with all configuration stored in components.json. The official Skill’s job is to pass this configuration and composition rules to coding assistants: first run info, then search / docs, and finally add. Starting with CLI v4, presets, dry-run, and MCP have been integrated into the same workflow.

Official links:
- Skill source code: https://github.com/shadcn-ui/ui/tree/main/skills/shadcn
- Documentation: https://ui.shadcn.com/docs/skills
- CLI: https://ui.shadcn.com/docs/cli
- MCP: https://ui.shadcn.com/docs/mcp
- Installation directory: https://www.skills.sh/shadcn/ui