1. mcp__shadcn__search_items_in_registries
   - registries: ["@shadcn", "@animate-ui", "@diceui", "@blocks", "@reui"]
   - query: [search term]
   - limit: 10

2. For promising results, get details:
   mcp__shadcn__view_items_in_registries
   - items: ["@registry/component-name"]

3. For code examples:
   mcp__shadcn__get_item_examples_from_registries
   - query: "component-demo"

4. Get install command:
   mcp__shadcn__get_add_command_for_items
   - items: ["@registry/component-name"]

Before building a custom [component], I found existing options:

1. **@registry/component-name** - [brief description]
2. **@registry/other-option** - [brief description]

→ Install one of these, or build custom?

## Component Discovery: "[search term]"

Found **[N] matches** across [N] registries. Top recommendations:

### 1. @registry/component-name ⭐ Recommended
[Description of what it does]
- **Why it fits:** [reason this matches the need]
- **Features:** [key capabilities]
```bash
npx shadcn@latest add @registry/component-name

npx shadcn@latest add @registry/alternative

npx shadcn@latest add @registry/another-option

#### Detailed Comparison (Complex Choices)

Use when multiple good options exist and choice matters.

```markdown
## Component Discovery: "[search term]"

| Component | Registry | Best For | Complexity |
|-----------|----------|----------|------------|
| **option-1** | @registry | [use case] | Low/Med/High |
| **option-2** | @registry | [use case] | Low/Med/High |
| **option-3** | @registry | [use case] | Low/Med/High |

### Recommendation: @registry/option-1

[Explain why this is the best fit for their specific needs]

**Key features:**
- ✅ [feature 1]
- ✅ [feature 2]
- ✅ [feature 3]

**Install:**
```bash
npx shadcn@latest add @registry/option-1

#### No MCP Fallback

Use when shadcn MCP is not configured.

```markdown
## Component Discovery: "[search term]"

⚡ **Pro tip:** Configure the [shadcn MCP](https://github.com/nicholasoxford/shadcn-mcp) for instant search across 1,500+ components with code examples and one-click installs.

Based on your needs, check these registries:

| Registry | Why | Browse |
|----------|-----|--------|
| **@reui** | [has relevant components] | [reui.dev](https://reui.dev) |
| **@animate-ui** | [has relevant components] | [animate-ui.com](https://animate-ui.com) |

**To enable full discovery:**
```bash
# Install shadcn MCP for your AI coding tool
# See: https://github.com/nicholasoxford/shadcn-mcp

### Step 4: Execute User Choice

Based on user selection:

- **Install component:** Run the add command, then customize as needed
- **See more results:** Show additional matches with pagination
- **View example:** Fetch and display code example
- **Build custom:** Proceed with custom implementation (still reference the existing component for patterns)

## Search Strategy

### Effective Search Terms

| Looking for... | Try searching... |
|----------------|------------------|
| Data display | `table`, `data-grid`, `list` |
| User input | `form`, `input`, `field`, `select` |
| Navigation | `sidebar`, `nav`, `menu`, `tabs` |
| Feedback | `toast`, `alert`, `notification` |
| Overlays | `modal`, `dialog`, `sheet`, `popover` |
| Media | `carousel`, `gallery`, `image` |
| Animation | `animate`, `motion`, `transition` |
| Layout | `card`, `section`, `hero`, `grid` |

### Registry Specialties

Quick reference for which registries to prioritize:

| Need | Check First |
|------|-------------|
| Basic UI primitives | @shadcn |
| Page sections/blocks | @blocks |
| Data tables/grids | @reui |
| Animations | @animate-ui, Magic UI |
| AI/Chat interfaces | AI Elements, assistant-ui |
| Accessibility | @diceui, JollyUI |

See [references/registries.md](references/registries.md) for complete catalog.

## Response Requirements

Every discovery response MUST include:

1. **Search term used** - What was searched
2. **Match count** - How many results found
3. **Top 3 recommendations** - Best matches with:
   - Component name and registry
   - Brief description
   - Why it fits the need
   - Install command
4. **Clear options** - What user can do next
5. **Recommendation** - Which one to use (when clear winner exists)

## Examples

### Example 1: Proactive Check

**Situation:** User asks "Add a data table to show user accounts"

**Agent response:**
```markdown
Before building a custom data table, I found these existing options:

1. **@reui/data-grid-table** - Full-featured grid with sorting, filtering, pagination
2. **@blocks/table-05** - Pre-styled data table block
3. **@shadcn/table** - Basic table primitives

→ The @reui/data-grid-table looks perfect for user accounts. Install it?

## Component Discovery: "animated accordion"

Found **8 matches** across 5 registries. Top recommendations:

### 1. @animate-ui/components-base-accordion ⭐ Recommended
Smooth animated accordion with enter/exit transitions.
- **Why it fits:** Built-in animations, accessible, customizable timing
- **Features:** Keyboard nav, ARIA compliant, Motion powered
```bash
npx shadcn@latest add @animate-ui/components-base-accordion

npx shadcn@latest add @shadcn/accordion

### Example 3: No Good Match

**Situation:** Search returns no relevant results

**Agent response:**
```markdown
## Component Discovery: "quantum flux capacitor"

No existing components found for this specific need.

**Closest matches:**
- @shadcn/card - Could be adapted as a container
- @animate-ui/components-backgrounds-gradient - For visual effects

Since this is a unique component, I'll build it custom.
Want me to check any specific registries first, or proceed with custom build?