shadcn-ui-skill

---
name: shadcn-ui-skill
description: Use when wiring shadcn/ui into a project so an AI agent reads components.json, runs the shadcn CLI, and composes registry components correctly.
source: https://ui.shadcn.com/docs/skills
generated: 2026-05-17T04:18:35.260Z
category: library
audience: engineers
---

## When to use

- Adding a shadcn/ui component to a Next.js or Vite project
- Building a login, settings, or dashboard form with shadcn primitives
- Switching color presets, OKLCH tokens, or dark mode on a shadcn theme
- Publishing or consuming a custom shadcn registry (registry.json)
- Wiring the shadcn MCP server for component search and install
- Migrating between Tailwind v3 and v4 with shadcn variables

## Key concepts

### components.json detection

The skill activates when a components.json file is present at the project root. It runs `shadcn info --json` to read framework, Tailwind version, path aliases, base library (radix or base), icon library, and the list of already-installed components, then injects that into the agent's context.

### shadcn CLI

Primary surface for installing and inspecting components. The skill documents the commands init, add, search, view, docs, diff, info, and build, including flags, dry-run mode, smart merge workflows, presets, and templates.

### Registry authoring

Publishers describe components in a registry.json file with item types, dependencies, CSS variables, and hosting rules. The skill knows how to author and consume custom registries so agents can pull blocks from third parties (e.g. @tailark).

### Composition rules

shadcn enforces composition patterns the skill teaches the agent: FieldGroup for grouped form fields, ToggleGroup for option selectors, and semantic color tokens (background, foreground, primary, muted) instead of raw Tailwind hues.

### MCP server integration

Optional shadcn MCP server exposes tools for searching the registry, browsing components, and installing from inside the agent — used before code generation so the agent picks an existing block over hand-rolling markup.

### Tailwind v3 vs v4 awareness

The skill carries customization knowledge for both Tailwind versions: CSS variables, OKLCH color definitions, dark mode strategy, custom colors, border radius scales, and component variants — and adapts output to whichever version components.json reports.

## API reference

```
pnpm dlx skills add shadcn/ui
```

Install the official shadcn/ui skill into the current project for any compatible coding agent.

```
pnpm dlx skills add shadcn/ui
```

```
shadcn info --json
```

Print the current project's shadcn config (framework, Tailwind version, aliases, base, icons, installed components) as JSON for context injection.

```
shadcn info --json
```

```
shadcn add <component>
```

Add a component or block from the default or a custom registry into the local codebase, respecting aliases in components.json.

```
shadcn add button
shadcn add login-01
shadcn add @tailark/hero-section
```

```
shadcn search <query>
```

Search registries for matching components or blocks before generating new code, so the agent reuses existing primitives.

```
shadcn search login
```

```
shadcn docs <component>
```

Pull official documentation for a component (props, slots, examples) into the agent's context window before writing usage code.

```
shadcn docs dialog
```

```
shadcn build
```

Build a custom registry from a registry.json file, producing the JSON payloads other projects can consume via `shadcn add`.

```
shadcn build
```

## Gotchas

- The skill only activates when components.json exists — running it in a project without shadcn initialized produces no context
- Agents must call `shadcn docs`, `shadcn search`, or the MCP tools before generating component code, not hand-roll markup
- Always use semantic color tokens (primary, muted, background) — raw Tailwind colors like bg-blue-500 violate shadcn composition rules
- Form fields must be wrapped in FieldGroup and option selectors in ToggleGroup; flat divs break shadcn patterns
- Tailwind v3 and v4 have different CSS variable formats — let `shadcn info --json` decide which version's customization rules apply
- Installing from a third-party registry (e.g. @tailark) requires that registry to be configured in components.json first

---
Generated by SkillMake from https://ui.shadcn.com/docs/skills on 2026-05-17T04:18:35.260Z.
Verify against source before relying on details.

File: ~/.claude/skills/shadcn-ui-skill/SKILL.md