shadcn-ui
Builds accessible, customizable component libraries using shadcn/ui with Radix UI or Base UI, Tailwind CSS 4, and React 19. Covers component ownership, oklch CSS theming, type-safe forms with Field and Zod, CLI workflows, and registry patterns. Use when adding shadcn/ui components, configuring themes, building forms with Zod, creating custom registries, or composing accessible component variants. Use for shadcn CLI, dark mode, component variants, form validation.
- Installs
- 159
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oakoss/agent-skills --skill shadcn-ui- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads shadcn-ui automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
shadcn/ui
Overview
Guides building accessible, customizable UI with shadcn/ui as a code generation platform (not an npm dependency). Components are copied into your project via the CLI and fully owned. Supports Radix UI or Base UI primitives, Tailwind CSS 4 with oklch color tokens, React 19 direct ref patterns, and type-safe form validation with the Field component and Zod.
When to use: Adding shadcn/ui components, theming with CSS variables and oklch colors, building forms with React Hook Form or TanStack Form, creating custom registries, composing accessible component variants, setting up dark mode.
When NOT to use: Non-React frameworks (use shadcn-vue or shadcn-svelte instead), projects using a different component library (MUI, Chakra), projects not using Tailwind CSS.
Quick Reference
| Pattern | API / Approach | Key Points |
|---|---|---|
| Init project | npx shadcn@latest init | Auto-detects framework, configures CSS variables |
| Add component | npx shadcn@latest add [name] | Copies source code into your project |
| Custom project | npx shadcn@latest create | Pick library (Radix/Base UI), style, theme, fonts |
| Check updates | npx shadcn@latest diff [component] | Shows upstream changes for your components |
| Search registry | npx shadcn@latest search @registry | Browse and install from namespaced registries |
| Build registry | npx shadcn@latest build | Generate registry JSON from registry.json |
| Theme tokens | :root vars + @theme inline mapping | oklch color values, dark mode via .dark class |
| Dark mode | @custom-variant dark (&:is(.dark *)) | Swaps CSS variables under .dark selector |
| Component variant | cva() from class-variance-authority | Type-safe variant definitions |
| Polymorphic slot | asChild prop with <Slot> from Radix | Merge props onto child element |
| Direct ref | ref as a regular prop | forwardRef is deprecated in React 19 |
| Form (current) | <Field /> + React Hook Form + Zod | Replaces legacy <Form /> component |
| Form (legacy) | <Form /> + <FormField /> + Zod | Still works but no longer actively developed |
| Class merging | cn() utility wrapping clsx + twMerge | Safely merge Tailwind classes without conflicts |
| Toast / notification | Sonner (npx shadcn@latest add sonner) | Default notification approach; auto-dismiss, stacking |
| Init with blocks | npx shadcn@latest init sidebar-01 | Bootstrap project with pre-built page blocks |
| RTL support | dir="rtl" on root element | Built-in RTL layout support for all components |
| New components | Spinner, Kbd, ButtonGroup | Recently added utility and layout components |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Installing shadcn/ui as an npm dependency | Use the CLI (npx shadcn@latest add) to copy source into your project |
Using forwardRef with React 19 components | Pass ref directly as a prop -- forwardRef is deprecated in React 19 |
| Using HSL values for color tokens | Use oklch format: --primary: oklch(0.205 0 0) |
Wrapping variables with hsl() or oklch() in utilities | Reference CSS variables directly: var(--primary) |
Putting tokens directly in @theme {} | Use :root for values + @theme inline to map them to Tailwind |
Using legacy <Form /> for new forms | Use <Field /> component with React Hook Form or TanStack Form |
| Skipping Zod validation in form components | Always pair forms with Zod schemas for type-safe validation |
Using div elements for interactive controls | Use Radix or Base UI primitives for semantic HTML and accessibility |
Modifying components in node_modules | Components live in your source tree -- own and customize directly |
Using old CLI command shadcn-ui@canary | Use npx shadcn@latest for all CLI operations |
Delegation
- Component discovery and primitive lookup: Use
Exploreagent - Theme migration or multi-file refactoring: Use
Taskagent - Design system architecture planning: Use
Planagent - Registry setup and distribution: Use
Taskagent
If the
tanstack-formskill is available, delegate advanced form state management (array fields, linked fields, async validation) to it. If thetailwindskill is available, delegate utility class patterns and design token architecture to it.
References
- Theming and dark mode
- Component patterns and variants
- Form patterns with Field, React Hook Form, and Zod
- CLI and registry
FAQ
What does the shadcn-ui skill do?
Builds accessible, customizable component libraries using shadcn/ui with Radix UI or Base UI, Tailwind CSS 4, and React 19. Covers component ownership, oklch CSS theming, type-safe forms with Field and Zod, CLI workflows, and registry patterns. Use when adding shadcn/ui components, configuring themes, building forms with Zod, creating custom registries, or composing accessible component variants. Use for shadcn CLI, dark mode, component variants, form validation.
How do I install shadcn-ui?
Run npx skills add https://github.com/oakoss/agent-skills --skill shadcn-ui in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/shadcn-ui/ (personal) or .claude/skills/shadcn-ui/ (project).
Which AI agents can use shadcn-ui?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is shadcn-ui safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains shadcn-ui?
It is published by oakoss in oakoss/agent-skills. It has 159 recorded installs.
More from oakoss/agent-skills
ui-ux-polish
oakoss/agent-skills
Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.
playwright
oakoss/agent-skills
Playwright browser automation API, web scraping, and tooling. Covers locator strategies, assertions, API testing, stealth mode, anti-bot bypass, authenticated sessions, screenshots/PDFs, Docker deployment, configuration, debugging, and MCP integration with AI agents. Prevents documented errors including CI timeout hangs, extension testing failures, and navigation issues. Use when automating browsers, scraping protected sites, bypassing bot detection, generating screenshots/PDFs, configuring Playwright Test, troubleshooting Playwright errors, or learning Playwright API patterns. For E2E test architecture, Page Object Models, CI sharding strategies, or test organization patterns, use the e2e-testing skill instead.
coolify
oakoss/agent-skills
Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration. Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
application-security
oakoss/agent-skills
Application security covering threat modeling (STRIDE), OWASP Top 10 (2025), OWASP API Security Top 10 (2023), secure coding review, authentication/authorization patterns, input validation, encryption, security headers, supply chain security, compliance (GDPR/HIPAA/SOC2/PCI-DSS), and security monitoring. Use when reviewing code for vulnerabilities, implementing auth patterns, securing APIs, configuring security headers, hardening supply chain, preventing injection attacks, or preparing for compliance audits.
find-skills
oakoss/agent-skills
Discovers and installs agent skills from the open ecosystem. Enriches search results with descriptions fetched from skills.sh. Use when a user asks "how do I do X", "find a skill for X", "is there a skill that can...", or wants to extend agent capabilities. Use for skill discovery, skill search, skill install, finding tools.
drizzle-orm
oakoss/agent-skills
Drizzle ORM for type-safe SQL with PostgreSQL, MySQL, and SQLite. Use when defining schemas, writing queries, managing relations, running migrations, or using drizzle-kit. Use for drizzle, orm, schema, query, migration, pgTable, relations, drizzle-kit, drizzle-zod.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.