102.7K+Download
Skip to the usage guide
shadcnby shadcn

shadcn Skill.

A Claude Code and Codex skill for UI design: adds, searches, fixes, styles, and composes shadcn components in a project.

  • Web & UI
  • UI code
Download OpenDesignView usage guide
shadcn-ui/ui · skills/shadcn/SKILL.mdSKILL.md
--- name: shadcn description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. 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". --- ## Current Project Context ## Principles ## Critical Rules ## Key Patterns ## Component Selection ## Key Fields
Front matter and section headings read from the upstream file on 2026-09-14 · 19,427 characters in full

01 What it does

What the shadcn Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

This skill manages shadcn/ui projects by adding, searching, fixing, and composing components. It instructs the agent to obtain project context through the CLI and components.json, enforces framework-specific rules for forms, styling, composition, icons, and chat UI, and uses the shadcn CLI for all operations. Components are installed as source code via npx shadcn@latest (or the project's package runner).

The skill applies when working with shadcn/ui, component registries, preset codes, or any project with a components.json file. It covers RSC directives, Tailwind v3/v4, Base UI vs Radix primitives, icon library detection, and monorepo layouts. Every command references the project's actual aliases, package manager, and resolved paths.

What it produces

  • Source code files for shadcn components added to the project's resolved ui path
  • Merged component files when updating, preserving local changes while applying upstream updates
See the example prompt ↗

How It Works

  1. 01
    Inject Project Context

    Runs npx shadcn@latest info --json to get the project config, installed components, aliases, RSC flag, Tailwind version, icon library, base (radix or base), and resolved paths.

  2. 02
    Search Registries Before Writing Custom UI

    Uses npx shadcn@latest search to check the shadcn registry and community registries for existing components that match the need.

  3. 03
    Fetch Component Docs and Examples

    Runs npx shadcn@latest docs <component> to get documentation and example URLs, then fetches them to verify correct API usage before creating or fixing a component.

  4. 04
    Add or Update Components with the CLI

    Use the project’s package runner with the shadcn CLI. For updates, inspect --dry-run and per-file --diff, preserve local edits, and obtain explicit approval before --overwrite. For preset changes, choose overwrite, partial theme/font, merge or skip rather than silently replacing components.

  5. 05
    Fix Imports in third-party Components

    After adding components from community registries, checks non-UI files for hardcoded paths like @/components/ui/...

  6. 06
    Review and Verify Added Components

    Reads all added files to check for missing sub-components, incorrect composition, violations of critical rules, and mismatched icon imports.

02 Find your fit

When to Use the shadcn Skill

Use the shadcn skill in Claude Code or Codex when the job is UI design of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

  • Building UI with shadcn/ui components in an existing project that has a components.json file
  • Initializing a new shadcn project with a preset code or named preset like nova or vega
  • Building chat or conversation interfaces using MessageScroller, Message, Bubble, Attachment, and Marker

Know the Boundaries

  • Manually fetching component files from GitHub instead of using the CLI
  • Defaulting to a registry when the user does not specify which one to use
  • Using --overwrite to update components without the user's explicit approval
  • Inventing capabilities, integrations, or file names not present in the project context

What to Provide

  • The project and change boundaryProvide the project directory, existing components.json and the requested UI behavior. State which local customizations must be kept. Preset replacement and component overwrite require a separate explicit choice.
  • Component or block nameThe name of a shadcn component (button, dialog, select) or a registry item (@magicui/shimmer-button, owner/repo/item) to add or search for.
  • Preset code or named presetA version-prefixed base62 string (e.g. a2r6bw) from ui.shadcn.com, or a named preset (nova, vega, maia, lyra, mira, luma) for init or apply.

03 Inside the skill

Rules the shadcn Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

  1. Use gap-, Never space-x- or space-y-*

    For spacing between flex children, use gap-. For vertical stacks, use flex flex-col gap-. space-x- and space-y- are never allowed.

  2. Forms Use FieldGroup + Field

    Form layouts must use FieldGroup and Field components. Never use raw div with space-y- or grid gap- for form layout.

  3. Icons in Buttons Use data-icon

    Icons inside Button must have data-icon="inline-start" or data-icon="inline-end". No sizing classes like size-4 or w-4 h-4 on icons inside components.

  4. Items Always Inside Their Group

    SelectItem goes inside SelectGroup, DropdownMenuItem inside DropdownMenuGroup, CommandItem inside CommandGroup. Never render items directly.

  5. Use Semantic Color Tokens, Not Raw Values

    Use bg-primary, text-muted-foreground, etc. Never use raw Tailwind colors like bg-blue-500 or text-emerald-600. No manual dark: color overrides.

  6. Dialog, Sheet, and Drawer Always Need a Title

    DialogTitle, SheetTitle, and DrawerTitle are required for accessibility. Use className="sr-only" if the title should be visually hidden.

  7. Never Decode Preset Codes Manually

    Use npx shadcn@latest preset decode <code>, preset url <code>, or preset open <code>. For project-aware preset detection, use preset resolve. Never build preset URLs by hand.

  8. Run All CLI Commands with the Project's Package Runner

    Use npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest based on the project's packageManager field. Never hardcode npx if the project uses pnpm or bun.

04 Put it to work

Install shadcn in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add shadcn to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

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

Generic skills CLI form for skills/shadcn/SKILL.md; the repository may document its own path.

Give the Skill a First UI Design Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt
I need a settings page with tabs for profile, account, and notifications. Each tab should have form fields grouped by section, with a save button at the bottom. Use the project's existing shadcn components and follow the FieldGroup pattern. The profile tab needs an avatar upload, the account tab needs email and password inputs with inline buttons to change them, and the notifications tab needs toggle groups for frequency (daily, weekly, monthly) and a set of checkboxes for notification types. Make sure all validation states use data-invalid and aria-invalid correctly.

Editorial example based on the reviewed source; not an executed task or an upstream quotation.

Check the First Result

What the SKILL.md itself says a correct result looks like:

  • Run npx shadcn@latest info to verify the component was added to the installed components list
  • Check that icon imports match the project's iconLibrary field (lucide-react, @tabler/icons-react, etc.)
  • Review the actual file diff for preserved local customizations and unapproved preset or component replacement. Test the changed UI and keyboard interactions in the project.

OpenDesign provides a local workspace for coding agents. Check the installed version for skill availability and setup; this source review does not verify bundled skills or include external tools and services.

Download OpenDesignRead the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author
shadcn
Repository
github.com/shadcn-ui/ui Branch main
Skill file
skills/shadcn/SKILL.md Content checksum recorded at verification; commit 2b3e6d4
License
MIT From LICENSE.md.
Repository stars
123,708 GitHub snapshot taken 2026-09-14 for the whole shadcn-ui/ui repository. Not a rating or usage count for shadcn.
Verified by OpenDesign
2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

  1. Current Project ContextInjects live project config and installed components from npx shadcn@latest info --json
  2. PrinciplesUse existing components first, compose instead of reinventing, use built-in variants, use semantic colors
  3. Critical RulesAlways-enforced rules for styling, forms, composition, icons, chat, and CLI with links to detailed files
  4. Key PatternsMost common code patterns: form layout, validation, icons in buttons, spacing, equal dimensions, status colors
  5. Component SelectionTable mapping UI needs to the correct shadcn components (buttons, forms, overlays, feedback, navigation, chat)
  6. Key FieldsExplains aliases, isRSC, tailwindVersion, base, iconLibrary, resolvedPaths, framework, packageManager, preset from project context
  7. Component Docs, Examples, and UsageRun npx shadcn@latest docs to get URLs, fetch them for correct API and usage patterns
  8. WorkflowNine-step process: get context, check installed, search, get docs, install, fix imports, review, handle registries, switch presets
  9. Updating ComponentsUse --dry-run and --diff to merge upstream changes while preserving local modifications, never use --overwrite without approval
  10. Quick ReferenceCLI command examples for init, apply, add, search, docs, view, preset operations with flags and registry syntax
  11. Detailed ReferencesLinks to separate rule files for forms, composition, chat, icons, styling, base-vs-radix, CLI, registry, customization
The Skill's Own Description
“Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. 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".”

Front-matter description from SKILL.md. The full file is about 19,427 characters. Read the full file on GitHub.

shadcn

Run shadcn on a Real UI Design Task.

Download OpenDesign, import shadcn from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/shadcn-ui/ui --skill shadcn