shadcn

Overview of shadcn skill

What the shadcn skill is for

The shadcn skill helps an AI assistant work correctly inside real shadcn/ui projects: finding components, installing them with the right CLI, composing screens from existing primitives, and avoiding common API mistakes across presets and component families. It is most useful when you want more than “generate a button” and need output that respects components.json, your installed registry items, your template, and the base vs radix differences.

Who should use this shadcn skill

Best fit readers are:

• developers already using shadcn/ui
• teams adopting a preset or registry-driven UI workflow
• people asking AI to add or refactor forms, dialogs, settings pages, dashboards, or theme work
• anyone who wants the assistant to inspect project context before writing JSX

If you are not using shadcn/ui, components.json, or the shadcn CLI, this skill is probably too specific.

The real job-to-be-done

Users do not just want a repo summary. They want the assistant to:

1. detect the project’s shadcn setup,
2. choose existing components before inventing new ones,
3. use the correct CLI commands and documented flags,
4. compose UI in the library’s preferred patterns,
5. avoid subtle breakage like wrong trigger composition, missing group wrappers, or incorrect form validation wiring.

That is where this shadcn skill adds value over an ordinary UI prompt.

What differentiates shadcn from a generic prompt

The strongest differentiators are practical:

• it starts from npx shadcn@latest info --json project context
• it emphasizes search, view, and docs before custom implementation
• it encodes project rules from files like rules/composition.md, rules/forms.md, rules/styling.md, and rules/base-vs-radix.md
• it covers theming and preset switching, not just component snippets
• it includes MCP guidance for registry search and installation workflows

In short, the shadcn skill is less about “write React” and more about “write the right React for this shadcn setup.”

Important adoption constraints

Before relying on the skill, know these constraints:

• it assumes shadcn CLI access via the project’s package runner: npx, pnpm dlx, or bunx --bun
• it is bounded by documented CLI flags; the skill explicitly warns against inventing flags
• many good outputs depend on a valid components.json
• API details can differ by preset and by base vs radix, so blindly reusing examples can be wrong

How to Use shadcn skill

Install context for the shadcn skill

Add the skill to your AI environment with the directory’s standard install flow, then use it in a repo that actually contains or intends to contain a shadcn setup. In practice, the repository-side requirement is more important than the skill install command: the assistant needs access to your project files and should be able to run shadcn CLI commands.

Inside the target project, the relevant runtime commands are:

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

Substitute pnpm dlx shadcn@latest or bunx --bun shadcn@latest if that matches the project’s package manager.

Read these files first before asking for output

For fast, accurate shadcn usage, inspect these files in roughly this order:

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

Why this order works:

• SKILL.md defines trigger conditions and workflow
• cli.md prevents guessed commands and flags
• the rules/ files capture the mistakes generic codegen often makes
• customization.md matters when you need theme-safe styling, not raw Tailwind color hacks
• mcp.md matters when your assistant can browse registries through MCP rather than shelling out

Start every shadcn task with project discovery

The single best first step is:

npx shadcn@latest info --json

This tells the assistant what is already configured, including component and project context. It is especially useful for:

• checking whether components.json exists
• identifying installed components
• detecting setup details that change valid code choices
• confirming the package runner and avoiding wrong command examples

If you skip this, the shadcn skill becomes much closer to a generic prompt.

Turn a rough goal into a strong shadcn prompt

Weak prompt:

Build me a profile dialog with shadcn.

Better prompt:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

Why this is stronger:

• it forces project discovery
• it specifies preset-sensitive behavior
• it states icon and styling constraints
• it asks for install steps when dependencies are missing

Use search and docs before custom code

A high-quality shadcn workflow is:

1. search registries for existing components,
2. inspect docs and examples,
3. add missing pieces,
4. compose the screen.

Practical commands:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

This is especially important for forms, overlays, navigation, and empty states, where the skill’s rules prefer library patterns over ad hoc div structures.

Compose screens from existing building blocks

The shadcn skill is strongest when you ask for composition, not monolithic custom UI. Good task framing includes:

• “settings page = Tabs + Card + form controls”
• “dashboard = Sidebar + Card + Chart + Table”
• “empty state = Empty component, not a custom centered div”
• “callout = Alert, not hand-rolled border boxes”

This mirrors the skill’s preferred workflow: use existing components first, then adapt variants and wrappers only when needed.

Respect base vs radix differences

One of the biggest adoption blockers is assuming all shadcn examples are interchangeable. They are not.

The skill includes explicit guidance for base vs radix, including:

• asChild vs render
• trigger composition differences
• nativeButton={false} in specific base-only cases
• component API differences such as Select, ToggleGroup, Slider, and Accordion

If your prompt does not state which setup you use, ask the assistant to detect it from npx shadcn@latest info.

Use styling guidance that survives theming

For shadcn for UI Design, better results come from semantic tokens and CSS variable-driven theming, not hard-coded Tailwind colors.

Prefer:

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

Avoid defaulting to:

• bg-red-500
• text-gray-400
• lots of manual dark: overrides

This matters because customization.md explains that components inherit from CSS variables. If the assistant uses semantic tokens, your design scales across light/dark themes and presets much more cleanly.

Handle forms the shadcn way

The evals and rules show that form quality is a real focus. Strong shadcn usage for forms usually means:

• using provided field layout patterns instead of raw stacked divs
• marking invalid state with data-invalid and aria-invalid
• using Switch for independent on/off preferences
• preferring gap-* spacing over space-y-* when the rules call for it

If your task includes validation, say so explicitly. Otherwise many assistants generate visually plausible but library-inconsistent forms.

Use MCP when your editor supports it

If your environment supports MCP, the shadcn skill can become more reliable for registry operations. mcp.md documents tools for:

• listing project registries
• searching registry items
• viewing item details and file contents
• getting examples
• installing items

This is useful when you want the assistant to browse registries conversationally instead of relying only on CLI output. It does not replace info --json for project config.

Practical prompt template for shadcn usage

Use this template when you want higher-quality output:

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

shadcn skill FAQ

Is this shadcn skill only for installing components?

No. shadcn install tasks are part of it, but the skill is broader: project inspection, registry search, component composition, theming, debugging, preset switching, and API-correct refactors are all in scope.

Is the shadcn skill beginner-friendly?

Yes, if you are already comfortable with React and a package manager. The skill reduces guesswork by pointing the assistant toward the right commands and rules. It is less beginner-friendly if you need a full introduction to React, Tailwind, or design systems from scratch.

When is shadcn better than a normal prompt?

Use the shadcn skill when correctness depends on project context:

• existing components.json
• matching installed components
• base vs radix behavior
• using documented CLI flags only
• preserving theme tokens and library composition rules

A normal prompt may produce plausible JSX, but it is more likely to miss installation steps or misuse component APIs.

When should you not use the shadcn skill?

Skip it if:

• your project does not use shadcn/ui
• you only need generic HTML/CSS mockups
• you want a design-system-agnostic answer
• the assistant cannot inspect files or run commands, and you cannot provide the needed context manually

In those cases, a broader frontend skill may be a better fit.

Does the skill help with shadcn for UI Design decisions?

Yes, especially around composition and theming. It nudges the assistant toward reusable primitives, semantic color tokens, correct overlay patterns, and component structures that are easier to maintain than one-off handcrafted layouts.

What usually breaks shadcn usage in AI outputs?

Common failures include:

• inventing unsupported CLI flags
• using wrong trigger composition for base vs radix
• creating custom UI instead of using an existing registry component
• styling with raw colors that fight the theme system
• omitting required subcomponents like titles, groups, or fallbacks

These are exactly the areas this skill is meant to tighten up.

How to Improve shadcn skill

Give the shadcn skill the missing context upfront

The highest-leverage improvement is better input. Include:

• framework or template (next, vite, astro, etc.)
• whether components.json exists
• base or radix if already known
• current icon set
• target component or screen
• whether the task includes install, refactor, or bugfix work

Even one sentence of concrete context can prevent the assistant from choosing the wrong APIs.

Ask for commands before code when components may be missing

If your project may not have the needed component installed, prompt like this:

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

This improves output because it separates environment changes from implementation, making the result easier to trust and apply.

Force rule-aware output for fragile component types

For forms, dialogs, dropdowns, sheets, drawers, and selects, explicitly ask the assistant to follow the rule files. Example:

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

This matters because many low-quality generations look fine but break accessibility or composition contracts.

Improve shadcn usage by specifying design constraints

A better UI prompt is not just “make it modern.” Include constraints such as:

• semantic tokens only
• no raw palette utilities
• dark mode must work without manual overrides
• use existing variants before custom classes
• prefer library empty states, alerts, separators, badges, and skeletons

These details materially improve first-pass quality in shadcn for UI Design work.

Iterate with targeted corrections, not full rewrites

After the first output, avoid saying only “try again.” Instead say:

• “Refactor this to use installed shadcn components only.”
• “Make this valid for base, not radix.”
• “Replace raw color classes with semantic tokens.”
• “Add the missing title/fallback/group wrappers required by shadcn.”
• “Show the exact shadcn add commands for anything assumed.”

This preserves good work while fixing the parts most likely to be wrong.

Validate against the repository’s strongest signals

To improve trust, compare the output against:

• cli.md for commands and flags
• rules/composition.md for structure
• rules/base-vs-radix.md for API correctness
• rules/forms.md for validation and layout patterns
• rules/styling.md and customization.md for theme-safe styling
• evals/evals.json for what “good” looks like in practice

That is the quickest way to tell whether the shadcn skill is producing repository-aligned output rather than generic UI code.