⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

shadcn-component-discovery

mattbx@mattbx⭐ 23 stars· last commit 6mo ago· 0 open issues

Discover shadcn-compatible components and registries across the entire ecosystem before writing any custom UI. Use PROACTIVELY before building tables, forms, modals, animations, dashboards, auth pages, or any UI component. Use when the user says "find a component for...", "is there something for...", "search registries", "what exists for...", or asks about shadcn blocks, Magic UI, Aceternity, ReUI, Animate UI, DiceUI, Tailark, AI Elements, or any other shadcn-compatible registry. Complements the official shadcn skill by surfacing registries beyond the user's configured `components.json` — use when exploring what's available to add, not just what's already installed.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 23 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

shadcn-skills

Two agent skills for working with shadcn/ui: one for discovering existing components across the ecosystem before building, one for reviewing custom components against shadcn design patterns.

Both follow the Agent Skills open standard and work with Claude Code, Cursor, Windsurf, OpenAI Codex CLI, Gemini CLI, GitHub Copilot, and other compatible tools.


Skills

shadcn-component-discovery

Searches the shadcn component ecosystem before building any custom UI. Activates proactively before Claude writes a table, form, modal, animation, or other common UI pattern — and explicitly when prompted to search registries.

What it covers:

  • Live search via the official shadcn MCP (npx shadcn@latest mcp init) or CLI fallback (npx shadcn@latest search)
  • Awareness of 30+ community registries beyond the user's configured components.json, organized by specialty (animations, AI interfaces, data grids, accessibility-first, etc.)
  • Response format: top 2–3 matches with registry-qualified name, description, and ready-to-run install command
  • Graceful handling when no match exists — recommends closest adjacencies and offers to build custom

How it complements the official shadcn skill: The official shadcn skill (shipped with CLI v4) searches registries already declared in components.json. This skill's scope is upstream — surfacing registries the user hasn't configured yet, and providing ecosystem-wide awareness when choosing which registries to add.

Example:

User: "Add a data table to show user accounts"

Agent: Before building custom, I found existing options:

       1. @reui/data-grid-table — Full-featured grid with sorting, filtering, pagination
       2. @shadcn/table — Unstyled primitives (pair with TanStack Table for sorting)

       @reui/data-grid-table looks like the fit — install it?

shadcn-component-review

Reviews custom components against shadcn design patterns. Activates proactively after writing or modifying a component, and explicitly when asked to review or audit.

What it checks:

  • Structure: data-slot attributes, composition vs forking, Radix vs Base UI primitive patterns
  • Spacing: gap-* in flex/grid (not space-y-*), Tailwind scale values, size-* for equal dimensions
  • Design tokens: semantic colors only (text-muted-foreground, bg-card, etc.) — flags any Tailwind color scale values
  • Composability: className via cn(), CVA variant patterns, prop typing
  • Responsive/a11y: mobile-first, touch targets, min-w-0, focus-visible states, motion preferences

How it complements the official shadcn skill: The official skill enforces rules at generation time. This skill is for post-hoc audit — reviewing components that already exist, especially ones built before the project standardized on a style, or written by contributors without shadcn context.

Visual styles supported: Vega, Nova, Maia, Lyra, Mira — per-style spacing, radius, and density expectations are applied based on the project's components.json or npx shadcn@latest info --json.

Example:

User: "Review this component"

Agent: ## Review: <PageHeader />

       Structure  ✅ data-slot present, composition clean
       Spacing    ⚠️ Uses space-y-4 in flex container (line 8) — swap to gap-4
       Tokens     ❌ text-neutral-500 on line 12 — use text-muted-foreground
       a11y       ⚠️ Missing min-w-0 on flex child (line 18)

       Want me to apply these fixes?

Installation

npx skills (recommended)

npx skills add mattbx/shadcn-skills

Install individual skills:

npx skills add mattbx/shadcn-skills --list   # preview available
npx skills add mattbx/shadcn-skills -s shadcn-component-discovery
npx skills add mattbx/shadcn-skills -s shadcn-component-review

Target specific agents:

npx skills add mattbx/shadcn-skills -a claude-code -a cursor

Manual installation

Copy the skill folders from skills/ to:

  • ~/.claude/skills/ — applies to all projects for the current user
  • .claude/skills/ — project-scoped

The same paths work for Cursor, Windsurf, and other compatible tools. Check your agent's documentation for skill directory locations.


Recommended Setup

Both skills work without any additional configuration, but work best with the official shadcn MCP:

# Adds the official shadcn MCP to your agent
npx shadcn@latest mcp init

The MCP enables real-time search of your configured registries with code examples and correct install commands. Without it, the skills fall back to CLI commands and manual registry links.


File Structure

skills/
├── shadcn-component-discovery/
│   ├── SKILL.md                    # Main skill — workflow, search paths, response format
│   └── references/
│       └── registries.md           # Registry catalog with configuration examples
│
└── shadcn-component-review/
    ├── SKILL.md                    # Main skill — review workflow, patterns, output format
    └── references/
        ├── theme-styles.md         # Per-style spacing, density, radius tables
        ├── review-checklist.md     # Expanded audit checklist by category
        └── animation-patterns.md  # CSS and Motion animation conventions

docs/
└── ROADMAP.md                      # Open ideas and contribution opportunities

Contributing

PRs welcome. The highest-value open areas are in docs/ROADMAP.md. For registry additions, include the registry name, URL template (https://example.com/r/{name}.json), and a one-line description of what it covers.

License

MIT

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/shadcn-component-discovery/SKILL.md7.8 KBupstream ↗
    ---
    name: shadcn-component-discovery
    description: Discover shadcn-compatible components and registries across the entire ecosystem before writing any custom UI. Use PROACTIVELY before building tables, forms, modals, animations, dashboards, auth pages, or any UI component. Use when the user says "find a component for...", "is there something for...", "search registries", "what exists for...", or asks about shadcn blocks, Magic UI, Aceternity, ReUI, Animate UI, DiceUI, Tailark, AI Elements, or any other shadcn-compatible registry. Complements the official shadcn skill by surfacing registries beyond the user's configured `components.json` — use when exploring what's available to add, not just what's already installed.
    ---
    
    # shadcn Component Discovery
    
    Surface existing components from across the shadcn ecosystem — including registries the user hasn't configured yet — before spending effort on custom implementations.
    
    ## How This Complements the Official shadcn Skill
    
    The official `shadcn` skill (shipped with CLI v4) searches the registries declared in the user's `components.json`. That's the right tool once the user has decided which registries to use.
    
    This skill fills the *upstream* gap: ecosystem-wide awareness. It helps the user find and choose registries they may not yet have configured — Magic UI for animations, Aceternity for hero sections, AI Elements for chat interfaces, ElevenLabs UI for voice components, and so on. Use this skill for "what exists out there"; let the official skill handle "install this thing I know about."
    
    When both skills apply, this one runs first (discovery), then the official skill takes over for installation and project-aware work.
    
    ## Core Principle
    
    Search before building. Most UI needs have been solved in the shadcn ecosystem. The cost of a 10-second registry check is almost always less than custom-building something that already exists.
    
    ## When to Trigger
    
    **Proactive triggers** (activate before writing any component code):
    
    - User asks to build a table, form, modal, sidebar, dashboard, auth page, landing section, animation, carousel, chart, or any standard UI pattern
    - User describes a feature that implies UI (e.g. "add user accounts management" → table; "let users pick a date range" → date picker)
    - User mentions building something "like X" where X is a common pattern
    
    **Explicit triggers** (user directly requests search):
    
    - "Find a component for..."
    - "Is there a shadcn component for..."
    - "Search registries for..."
    - "What exists for..."
    - "Any good [category] components?"
    - Direct mentions of specific registries (@animate-ui, Magic UI, Aceternity, Tailark, etc.)
    
    ## Workflow
    
    ### Step 1: Clarify the Need
    
    Before searching, confirm:
    
    - **Functionality**: What must it do? (e.g. sortable + filterable + paginated table)
    - **Style**: Animated, minimal, accessible-first, dense, brutalist?
    - **Constraints**: Must support keyboard nav? Drag-drop? Mobile-first? SSR?
    
    A two-sentence clarification beats five searches with the wrong query.
    
    ### Step 2: Search
    
    Three paths depending on tool availability. The **official shadcn MCP** is strongly preferred when the user has a shadcn project — it returns real results with code examples.
    
    #### Path A: Official shadcn MCP (preferred)
    
    If the shadcn MCP server is running (configured via `npx shadcn@latest mcp init` or equivalent), use its tools directly:
    
    ```text
    1. mcp__shadcn__search_items_in_registries
       - registries: ["@shadcn", "@blocks", "@animate-ui", "@reui", "@diceui"]
       - query: "<search term>"
       - limit: 10
    
    2. For promising results, get full details:
       mcp__shadcn__view_items_in_registries
       - items: ["@registry/component-name", "@registry/other"]
    
    3. For implementation examples:
       mcp__shadcn__get_item_examples_from_registries
       - query: "<component>-demo"
    
    4. For the install command:
       mcp__shadcn__get_add_command_for_items
       - items: ["@registry/chosen-component"]
    ```
    
    The MCP only searches registries configured in the user's `components.json`. If the user is looking for something specialized, suggest adding a relevant registry to `components.json` first — see `references/registries.md` for recommendations and configuration snippets.
    
    #### Path B: shadcn CLI (no MCP, but shadcn project)
    
    If there's a `components.json` but no MCP is configured, use the CLI commands that shipped with CLI v3:
    
    ```bash
    # Search across configured registries
    npx shadcn@latest search "<term>"
    
    # Preview a component before installing
    npx shadcn@latest view @registry/component-name
    
    # List everything available in a registry
    npx shadcn@latest list @registry
    ```
    
    Suggest adding the MCP for better agent integration: `npx shadcn@latest mcp init`.
    
    #### Path C: No project context
    
    If there's no shadcn project yet, or the user is just exploring:
    
    - Recommend registries from `references/registries.md` based on their described need
    - Link directly to the registry's website so they can browse
    - Offer to help set up a shadcn project (`npx shadcn@latest init`) once they've picked direction
    
    ### Step 3: Present Findings
    
    Match the response format to the context. Keep it scannable — the user is about to make a decision, not read an essay.
    
    #### Proactive check (during build flow)
    
    When the user didn't explicitly ask to search but you searched anyway:
    
    ```markdown
    Before building custom, I found existing options:
    
    1. **@registry/component-name** — [one-line description]
    2. **@registry/alternative** — [one-line description]
    
    Want me to install one, or build custom?
    ```
    
    Keep it under five lines. The user is in flow; don't derail them.
    
    #### Explicit search (user asked)
    
    ```markdown
    ## Results for "<query>"
    
    **Top matches:**
    
    ### @registry/component-name ⭐
    [What it does in one sentence]
    - Fits because: [specific to their need]
    - Install: `npx shadcn@latest add @registry/component-name`
    
    ### @registry/alternative
    [What it does in one sentence]
    - Fits because: [specific to their need]
    - Install: `npx shadcn@latest add @registry/alternative`
    
    ---
    Install [1] or [2], see more results, view code example, or build custom?
    ```
    
    #### Comparison (multiple good options, choice matters)
    
    Use a short table when 3+ options are genuinely viable and trade off differently. Follow with a recommendation and the install command for the recommended one. Don't table-ify everything — it's heavier than plain prose and should earn its place.
    
    ### Step 4: Execute the Choice
    
    - **Install chosen**: Run the `add` command, then customize via props / composition as needed
    - **See more**: Return additional matches, continue pagination
    - **View code**: Fetch example via `get_item_examples_from_registries` or the registry's demo URL
    - **Build custom**: Proceed — but reference the closest existing component for composition patterns (CVA, `cn()`, `data-slot`, semantic tokens)
    
    ## Search Strategy
    
    ### Effective Query Terms
    
    Short, concrete nouns work best. Keep queries to 1–3 words.
    
    | Looking for… | Try searching… |
    |---|---|
    | Data display | `table`, `data-grid`, `list` |
    | User input | `form`, `input`, `field`, `select`, `combobox` |
    | Navigation | `sidebar`, `nav`, `menu`, `tabs`, `breadcrumb` |
    | Feedback | `toast`, `sonner`, `alert`, `notification` |
    | Overlays | `dialog`, `modal`, `sheet`, `popover`, `drawer` |
    | Media | `carousel`, `gallery`, `image` |
    | Animation | `animate`, `motion`, `transition` |
    | Layout | `card`, `section`, `hero`, `grid`, `stack` |
    | Date/time | `calendar`, `date-picker`, `date-range` |
    
    ### Registry Specialties (Quick Pick)
    
    | Need | Check first |
    |---|---|
    | Core UI primitives | `@shadcn` |
    | Page sections, pre-built blocks | `@blocks`, Tailark, HextaUI |
    | Data grids, advanced tables | `@reui` |
    | Animated components | `@animate-ui`, Magic UI, Aceternity UI |
    | AI / chat interfaces | AI Elements, assistant-ui |
    | Accessibility-first (React Aria) | `@diceui`, JollyUI, Intent UI |
    | Voice / audio | ElevenLabs UI |
    | Marketing / landing pages | Tailark, Eldora UI |
    | Style variants (brutalist, retr
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/mattbx-shadcn-skills-skills-shadcn-component-discovery.md

// REPO STATS

23 stars
0 open issues
Last commit: 6mo ago