Skip to content
Back to skills

Shadcn Ops

ASecurity

Use when building or fixing UI with shadcn/ui or in any project with a components.json: init, add, view, search, docs, info, presets and apply, Base UI vs Radix vs React Aria, Tailwind v4 theming with CSS variables, dark mode, admin dashboards (sidebar, dashboard and login blocks, data tables on TanStack Table, forms with Field and React Hook Form or TanStack Form, dialogs, sheets, toasts, charts, empty and loading states), monorepos, migrate, eject, registry authoring (registry.json, shadcn ...

  • 82 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
ai-agentspythonrustgoshellbashreactnextjsawstestinggit

Works with

  • claude code
  • cli
  • api
  • mcp

Security analysis

A100/100

Pro scans all 20 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add 0xDarkMatter/claude-mods --skill shadcn-ops --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Shadcn Ops?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Shadcn Ops
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/0xdarkmatter-shadcn-ops/badge)](https://www.skillsdirectory.com/skills/0xdarkmatter-shadcn-ops)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: shadcn-ops
description: "Use when building or fixing UI with shadcn/ui or in any project with a components.json: init, add, view, search, docs, info, presets and apply, Base UI vs Radix vs React Aria, Tailwind v4 theming with CSS variables, dark mode, admin dashboards (sidebar, dashboard and login blocks, data tables on TanStack Table, forms with Field and React Hook Form or TanStack Form, dialogs, sheets, toasts, charts, empty and loading states), monorepos, migrate, eject, registry authoring (registry.json, shadcn build), third-party registries and the shadcn MCP server. Runs the CLI pinned, never @latest; ships a project audit."
license: MIT
allowed-tools: "Read, Edit, Write, Glob, Grep, Bash(bash *shadcn-ops/scripts/*), Bash(pnpm exec shadcn info *), Bash(pnpm exec shadcn docs *), Bash(pnpm exec shadcn view *), Bash(pnpm exec shadcn search *), Bash(pnpm exec shadcn add --dry-run *), Bash(npx --no shadcn info *), Bash(npx --no shadcn docs *), Bash(npx --no shadcn view *), Bash(npx --no shadcn search *), Bash(npx --no shadcn add --dry-run *), Bash(yarn run shadcn info *), Bash(yarn run shadcn docs *), Bash(yarn run shadcn view *), Bash(yarn run shadcn search *), Bash(yarn run shadcn add --dry-run *), Bash(bunx --no-install shadcn info *), Bash(bunx --no-install shadcn docs *), Bash(bunx --no-install shadcn view *), Bash(bunx --no-install shadcn search *), Bash(bunx --no-install shadcn add --dry-run *), Bash(shadcn info *), Bash(shadcn docs *), Bash(shadcn view *), Bash(shadcn search *), Bash(shadcn add --dry-run *)"
metadata:
  author: claude-mods
  related-skills: "react-ops, tailwind-ops, nextjs-ops, supply-chain-defense, a11y-ops, figma-ops, package-manager-ops, test-engineering, playwright-ops"
---

# shadcn/ui Operations

**Why:** shadcn/ui copies component source into your project through a CLI that ships
several releases a month. Its docs and official agent skill run that CLI as `@latest`,
unpinned and pre-approved. This skill runs a pinned CLI, treats every registry as code you
are about to install, and goes deep on the admin dashboards most projects build with it.

> Versions verified 2026-11-10 against shadcn 4.23.0 (published 2026-10-27, no install
> scripts, Socket supply-chain score 97), ui.shadcn.com/docs and its llms.txt index. The pin
> and the other moving facts live in `assets/shadcn-facts.json`;
> `scripts/check-shadcn-facts.py --offline` keeps this text in step with it, and `--live`
> (weekly) fails when npm or the CLI moves.

## Hard rules

1. **Never run `shadcn@latest`**, a dist-tag (`@canary`, `@beta`), a range (`@4`), or an
   unversioned `pnpm dlx shadcn` / `yarn dlx shadcn`. Resolve the runner once per project:

   ```bash
   bash "<skill-dir>/scripts/shadcn-cmd.sh"     # {"prefix":"pnpm exec shadcn","source":"project",...}
   ```

   Then type that literal prefix in every command (`pnpm exec shadcn info --json`). This
   skill writes it as `$SHADCN`; don't store it in a shell variable, which neither survives
   between tool calls nor matches the pre-approved forms in `allowed-tools`. Order: the
   project's own devDependency, then a global `shadcn` of the pin's major, then
   `<pm> dlx shadcn@<pin>`. Exit 10 means run the frozen install first; exit 5 means nothing
   pinned is available. Only `info`, `docs`, `view`, `search` and `add --dry-run` (flag
   first) are pre-approved on a local or global runner: every write and every one-off
   download asks first, by design.
2. **Read the project before writing code:** `$SHADCN info --json` nests its answers:
   `config.base`, `config.style`, `config.iconLibrary`, `config.aliases`,
   `config.resolvedPaths`, `project.tailwindVersion`, `project.tailwindCss`, `project.rsc`,
   and `components` (installed). At a monorepo root it exits 1 with
   `"error": "monorepo_root"` and the workspaces in `targets`: rerun with `-c <workspace>`.
   Never assume the base, the icon library or the import alias.
3. **Third-party registries are untrusted code.** For anything not from `@shadcn`: `view`,
   then `add --dry-run <item>`, then `add --dry-run <item> --diff <file>` (or `--view
   <file>`) per file, and read the dependencies, target paths and network calls before the
   real `add`. Never pick a registry for the user.
4. **`add` installs npm packages.** New ones follow the supply-chain rule: a 7-day cooldown
   and a behavioural scan (supply-chain-defense owns how), with the lockfile change committed
   beside the component.
5. **Installed components are the user's code.** Update with `add --dry-run <item>` and
   `add --dry-run <item> --diff <file>`, merge by hand, and use `--overwrite` only with the
   user's OK, after a commit.
6. **Ask, and commit first, before project-wide rewrites:** `apply` (overwrites
   components), `init --force`, `migrate`, `add --all --overwrite`, and `eject`, which is
   irreversible.
7. **Write for the project's base.** Radix uses `asChild`; Base UI uses `render` (plus
   `nativeButton={false}` for non-buttons); React Aria keeps its own API. Select,
   ToggleGroup, Slider, Accordion and toasts differ too.
8. **Compose, don't restyle.** Existing components before markup, variants before classes,
   semantic tokens (`bg-primary`, `text-muted-foreground`) never raw colours, `gap-*` not
   `space-y-*`, items inside their groups, and a title on every Dialog, Sheet and Drawer.
9. **Don't add the shadcn MCP server to Claude Code.** It duplicates the CLI, runs in every
   session, and its documented config is unpinned. If a user insists, use the pinned
   project-scoped form in `assets/mcp.json.example`.
10. **Verify every change:** typecheck and build after an `add`, read the files it wrote
    (imports, icon library, composition), and check keyboard and screen-reader basics;
    a11y-ops runs full audits.

## Start here

1. Resolve the CLI (rule 1).
2. Audit the project. It only reads files; it never runs the CLI, a package manager or git:

   ```bash
   bash "<skill-dir>/scripts/run-python.sh" "<skill-dir>/scripts/shadcn-audit.py" .
   bash "<skill-dir>/scripts/run-python.sh" "<skill-dir>/scripts/shadcn-audit.py" apps/web --json | jq '.data[]'
   ```

   Exit 10 means findings (severity, id, `file:line`, message, fix; high first), 0 clean,
   3 no components.json or not shadcn's (at a monorepo root it names the workspaces), 4
   invalid JSON or a facts file missing a key.
3. `$SHADCN info --json`, then `$SHADCN docs <component>` and fetch the URLs it prints
   before using a component whose API you haven't read in this session.
4. Find before you build: `$SHADCN search @shadcn -q "<need>"`, and blocks before pages.
5. Add, read what was written, fix imports and icons, typecheck.

## Route by task

| Task | Read |
|---|---|
| CLI commands and flags, the runner, updating installed components, bumping the pin | [cli-and-pinning.md](references/cli-and-pinning.md) |
| What `add` changes, trust by source, reviewing an item, private registries and tokens | [supply-chain-and-registries.md](references/supply-chain-and-registries.md) |
| components.json fields, styles, aliases, Tailwind v3 vs v4 | [components-json.md](references/components-json.md) |
| Base UI vs Radix vs React Aria: `asChild`/`render`, Select, toasts, changing base | [bases.md](references/bases.md) |
| Styling and composition rules, icons, which component for which need, chat UIs | [composition-rules.md](references/composition-rules.md) |
| Forms: Field, React Hook Form, TanStack Form, validation, server errors | [forms.md](references/forms.md) |
| Data tables: TanStack Table v9, row actions, server-side paging, states | [data-tables.md](references/data-tables.md) |
| Dashboard shell: blocks, sidebar, dialogs and sheets, toasts, page states, auth pages, dark mode | [admin-layouts.md](references/admin-layouts.md) |
| Charts and KPI cards (Recharts v3) | [charts.md](references/charts.md) |
| Theme tokens, custom colours, radius, presets, `apply` | [theming.md](references/theming.md) |
| A design system from a DESIGN.md or brand spec | [design-systems.md](references/design-systems.md) |
| `migrate`, Tailwind v3 to v4, React 19, `eject` | [migrations-and-eject.md](references/migrations-and-eject.md) |
| Monorepos (`init --monorepo`, two components.json files) | [monorepo.md](references/monorepo.md) |
| Publishing your own registry (`registry.json`, `build`, GitHub registries) | [registry-authoring.md](references/registry-authoring.md) |
| The shadcn MCP server | [mcp.md](references/mcp.md) |
| Testing components: Vitest, Testing Library, jsdom gaps, real-browser runs | [testing.md](references/testing.md) |

## Admin dashboards at a glance

| Need | Use | Notes |
|---|---|---|
| The whole shell | `$SHADCN add --dry-run dashboard-01`, then adapt | or a `sidebar-01`..`sidebar-16` block |
| Navigation | `Sidebar` (`collapsible="icon"`, tooltips on items), `Breadcrumb` | Cmd/Ctrl+B toggles |
| Lists | the data-table guide (TanStack Table v9) on `Table` | server-side paging when data is large |
| Create and edit | `Dialog` + `Field` forms; `Sheet` for side panels | validate on client and server |
| Delete and other irreversible actions | `AlertDialog` naming the action | never straight from a menu item |
| Feedback | Base UI `toast`; Radix and React Aria Sonner | one `<Toaster />` in the root layout |
| KPIs and trends | `Card` + `Badge`; `Chart` with `min-h-*` | colours from `--chart-1..5` |
| Loading, empty, failed | `Skeleton`, `Empty`, `Alert variant="destructive"` | distinguish "none yet" from "no matches" |
| Login and sign-up | `login-*`, `signup-*` blocks | layout only; wire your auth |
| Theme | `next-themes` (Next.js) or the Vite ThemeProvider; `.dark` tokens | check contrast in both |

New projects start on Tailwind CSS v4 and React 19 with `--base base` (the default) unless
told otherwise; check an existing project's lines with the audit before writing code for it.

## Scripts and assets

| Resource | Use |
|---|---|
| `scripts/shadcn-cmd.sh [--cwd DIR] [--prefix \| --json] [--pm PM] [--no-dlx]` | the pinned runner; default output is JSON `{prefix, source, version, pm, pin, installed, workspace}`; `workspace` is null, or the monorepo workspace that declares shadcn (`"packages/ui"`): run the CLI from there |
| `scripts/shadcn-audit.py [DIR] [--json] [--ignore ID] [--checks]` | read-only audit; `--checks` lists the 20 check ids |
| `scripts/check-shadcn-facts.py --offline` | after editing the facts, SKILL.md or a reference: pin, read-only allowed-tools, code blocks and prose agree |
| `scripts/check-shadcn-facts.py --live` | weekly: npm (pin age, majors, install scripts, ecosystem majors) and the pinned CLI's `--help`; exit 7 is advisory |
| `scripts/run-python.sh` | launches the `.py` scripts with the first real Python 3.8+ |
| `assets/shadcn-facts.json` | the pin, cooldown and age policy, commands, migrations, bases, styles, ecosystem majors |
| `assets/mcp.json.example` | a pinned, project-scoped `.mcp.json` for those who use the MCP server anyway |

The audit's checks: components.json shape (`config-missing-field`, `style-unknown`,
`style-deprecated`), files (`css-missing`, `tailwind-config-missing`, `tailwind-mismatch`;
v4 CSS with `@config` is fine), aliases resolved as the CLI does (`alias-unresolved`,
`alias-missing`), the CLI pin (`shadcn-css-orphan`, `cli-range-open`, `cli-unlocked`,
`cli-old-major`, and `cli-not-installed`: runs use a global or downloaded copy; low when a
sibling workspace declares shadcn), unpinned runs in package.json scripts, README,
AGENTS.md, CLAUDE.md and MCP configs read as JSONC (`unpinned-cli`, `unpinned-mcp`),
registries (`third-party-registry`, `registry-insecure-url`, `registry-literal-secret` in
headers, params, URL queries or URL passwords; values never printed), `react-pre-19` and
`monorepo-mismatch`. `--ignore <id>` records a deliberate exception.

## Boundaries

| Topic | Owner |
|---|---|
| Tailwind itself: utilities, `@theme`, the v4 engine, plugins | tailwind-ops |
| React patterns, hooks, state, error boundaries | react-ops |
| Next.js App Router: server/client boundary, Server Actions, caching, `loading.tsx`/`error.tsx` | nextjs-ops |
| Vetting a package: cooldown, Socket, IOCs, install scripts | supply-chain-defense |
| Lockfiles, package managers, workspaces, npx discipline | package-manager-ops |
| Accessibility audits and WCAG | a11y-ops |
| Figma designs to shadcn code (Figma MCP, Code Connect) | figma-ops |
| Test strategy: what deserves a test, mocking, flaky and slow suites | test-engineering |
| End-to-end and real-browser suites | playwright-ops |

## Sources

- ui.shadcn.com/docs (the llms.txt page index): CLI, components.json, theming, Tailwind v4,
  forms, data table, sidebar, chart, toast, sonner, dark mode, monorepo, registry, MCP, and
  the changelog through October 2026.
- `shadcn --help` for every command of 4.23.0, and the CLI source at the `shadcn@4.23.0` tag
  (`info --json` shape, `init` preset handling); npm registry metadata; Socket's score.
- shadcn-ui/ui source: the init templates, the registry base definitions (which packages
  `init` installs, including the `shadcn` devDependency) and the `eject` command.
- The official shadcn skill (shadcn-ui/ui `skills/shadcn/`, MIT licence, last changed
  2026-10-14), ported and adapted; each reference that draws on it says so.

Files in this skill

  • SKILL.md13 KB
  • assets/mcp.json.example113 B
  • assets/shadcn-facts.json2.8 KB
  • references/admin-layouts.md7.7 KB
  • references/bases.md7.7 KB
  • references/charts.md2.6 KB
  • references/cli-and-pinning.md11.5 KB
  • references/components-json.md6.2 KB
  • references/composition-rules.md6.7 KB
  • references/data-tables.md11.2 KB
  • references/design-systems.md6.6 KB
  • references/forms.md12.3 KB
  • references/mcp.md2.2 KB
  • references/migrations-and-eject.md5.5 KB
  • references/monorepo.md3.4 KB
  • references/registry-authoring.md7.5 KB
  • references/supply-chain-and-registries.md8.6 KB
  • references/testing.md5 KB
  • references/theming.md5.4 KB
  • scripts/check-shadcn-facts.py27.6 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.