# install-pattern

> Install and fix AI SDK patterns from registries (aisdkagents.com, local). Handles ModelSelector integration, API configuration, test setup, registry generation, and verification. Automatically creates todo lists and avoids common issues.

- Author: CrazySwami
- Repository: mirror-factory/hustle-together-ai
- Version: 20260126113327
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/mirror-factory/hustle-together-ai
- Web: https://mule.run/skillshub/@@mirror-factory/hustle-together-ai~install-pattern:20260126113327

---

---
name: install-pattern
description: Install and fix AI SDK patterns from registries (aisdkagents.com, local). Handles ModelSelector integration, API configuration, test setup, registry generation, and verification. Automatically creates todo lists and avoids common issues.
---

# Install Pattern Skill

## Overview

This skill helps install AI SDK patterns from external registries and ensures they work correctly in the playground. It handles:

1. Pattern installation via shadcn CLI
2. Fixing 5 common issues with external patterns
3. Verification with 10-phase checklist
4. Test configuration setup
5. Registry generation for Code tabs

## When to Use

- User says "install X pattern"
- User provides CLI command from aisdkagents.com
- User wants to create custom pattern
- Pattern installed but not working

## Quick Start

### Option 1: Install from aisdkagents.com

User provides CLI command:
```bash
npx shadcn add 'https://www.aisdkagents.com/pro-registry/PATTERN?token=XXX'
```

Follow: [Installation Workflow](#installation-workflow)

### Option 2: Create Custom Pattern

User describes desired functionality. Follow: [Custom Pattern Workflow](#custom-pattern-workflow)

## Installation Workflow

### Step 1: Pre-Installation

**ALWAYS install AI Elements first** if pattern uses artifacts/chat:

```bash
npx ai-elements@latest
```

### Step 2: Run Installation Command

```bash
# Auto-accept prompts
yes y | npx shadcn add 'URL_FROM_USER'
```

### Step 3: Check for Common Issues

Artifact patterns from external registries often have 5 critical issues. See:
**→ [references/fixing-artifacts.md](references/fixing-artifacts.md)**

Quick check:
```bash
# Check ModelSelector present
grep -q "ModelSelector" components/playground/patterns/*/demo.tsx && echo "✓" || echo "✗"

# Check API endpoint correct
grep -q "/api/playground/" components/playground/patterns/*/*.tsx && echo "✓" || echo "✗"

# Check getProvider used
grep -q "getProvider" app/api/playground/**/route.ts && echo "✓" || echo "✗"

# Check test config exists
grep -q "PATTERN_NAME" lib/testing/pattern-routes.ts && echo "✓" || echo "✗"

# Check registry file count
cat registry/PATTERN.json | jq '.files | length'
```

### Step 4: Fix Issues (if any)

For artifact patterns, follow the fixing guide:
**→ [references/fixing-artifacts.md](references/fixing-artifacts.md)**

Create todo list using template from:
**→ [references/todo-templates.md](references/todo-templates.md)**

### Step 5: Comprehensive Verification

Run 10-phase verification checklist:
**→ [references/verification.md](references/verification.md)**

### Step 6: Test in Terminal

```bash
# Test the pattern
node scripts/run-all-tests.mjs --pattern PATTERN_NAME
```

### Step 7: Frontend Verification (For Artifact Patterns)

**IMPORTANT:** Terminal tests only validate the API. For artifact patterns (table, canvas), you MUST manually verify the UI works:

**Interview the user:**

```
I've completed the pattern installation and fixes. Now we need to verify the frontend works.

Please complete these manual checks:

1. Start the dev server:
   pnpm dev

2. Open browser to: http://localhost:3000

3. Navigate to: [Category] → [Pattern Name]

4. Verify UI loads:
   - [ ] ModelSelector visible with 27+ models
   - [ ] Chat input present
   - [ ] No console errors

5. Test artifact generation:
   - [ ] Type: "Create [artifact type] with [requirements]"
   - [ ] Press Enter
   - [ ] Verify: Does the artifact render on screen?
   - [ ] Check: Is the data correct?

6. Test operations:
   - [ ] Try an operation like "Add column" or "Filter data"
   - [ ] Verify: Does the artifact update?

7. Test model switching:
   - [ ] Change model from GPT-4o to Claude Sonnet
   - [ ] Send new prompt
   - [ ] Verify: Does it work with the new model?

Please confirm: Did all checks pass? (yes/no)
```

**If user reports issues:** Debug using [common-errors.md](references/common-errors.md)

**If all pass:** Mark pattern installation complete ✅

## Custom Pattern Workflow

### Step 1: Research with Context7

```bash
# Search aisdkagents for similar patterns
curl -s "https://context7.com/api/v2/context?libraryId=/websites/aisdkagents&query=PATTERN_TOPIC&type=txt"
```

### Step 2: Plan Architecture

- Review existing patterns in `lib/patterns/config.ts`
- Check model capabilities needed
- Determine test variations

### Step 3: Create Files

Follow structure:
```
app/api/playground/CATEGORY/PATTERN/route.ts
components/playground/patterns/CATEGORY/PATTERN-demo.tsx
```

### Step 4: Add Test Configuration

Add to `lib/testing/pattern-routes.ts`

### Step 5: Generate Registry

Create `registry/PATTERN.json` with all files

## Common Issues

For detailed troubleshooting, see:
**→ [references/common-errors.md](references/common-errors.md)**

Quick fixes:
- **Import errors**: Check import paths, install dependencies
- **Model not found**: Use `getProvider()` not `gateway()`
- **Build cache**: Run `rm -rf .next && pnpm dev`
- **Wrong endpoint**: Use `/api/playground/CATEGORY/PATTERN`
- **Registry incomplete**: Regenerate with all files
- **AI Elements missing**: Run `npx ai-elements@latest`

## Examples

See complete walkthroughs:
**→ [references/examples.md](references/examples.md)**

- Example 1: Install Routing Pattern (~15 min)
- Example 2: Fix Artifact Table Pattern (~30 min, 5 issues fixed)

## TODO List Templates

**ALWAYS create a todo list** when installing/fixing patterns:
**→ [references/todo-templates.md](references/todo-templates.md)**

Quick template (10 items):
```typescript
TodoWrite({
  todos: [
    { content: "Install AI Elements", activeForm: "Installing AI Elements", status: "in_progress" },
    { content: "Run installation command", activeForm: "Running installation", status: "pending" },
    { content: "Add ModelSelector", activeForm: "Adding ModelSelector", status: "pending" },
    { content: "Fix API endpoint", activeForm: "Fixing API endpoint", status: "pending" },
    { content: "Update API route", activeForm: "Updating API route", status: "pending" },
    { content: "Add test config", activeForm: "Adding test config", status: "pending" },
    { content: "Run build", activeForm: "Running build", status: "pending" },
    { content: "Test in browser", activeForm: "Testing in browser", status: "pending" },
    { content: "Run Model Tester", activeForm: "Running Model Tester", status: "pending" },
    { content: "Verify functionality", activeForm: "Verifying functionality", status: "pending" }
  ]
});
```

Comprehensive template (42 items) for artifact patterns available in todo-templates.md.

## Best Practices

1. **Always use TodoWrite** - Track all tasks systematically
2. **Check for common issues** - Run verification script
3. **Test after installation** - Don't assume it works
4. **Clean rebuilds** - `rm -rf .next` after major changes
5. **Verify Code tab** - Ensure registry has 20+ files
6. **Use Context7** - Look up documentation when needed
7. **Update registry** - After adapting, regenerate registry files
8. **Document changes** - Add comments explaining adaptations

## Reference Files

All detailed content has been moved to reference files for progressive disclosure:

- **[fixing-artifacts.md](references/fixing-artifacts.md)** - Fix 5 common issues with external patterns (~600 lines)
  - Pre-Installation: AI Elements
  - Issue 1: Missing ModelSelector
  - Issue 2: Wrong API Endpoint
  - Issue 3: Hardcoded Model
  - Issue 4: Missing Test Configuration
  - Issue 5: Incomplete Registry

- **[verification.md](references/verification.md)** - 10-phase comprehensive checklist (~400 lines)
  - Phase 1: Code Verification (7 items)
  - Phase 2: Build Verification (3 items)
  - Phase 3: Dev Server Verification (4 items)
  - Phase 4: UI Verification (6 items)
  - Phase 5: Functionality Verification (8 items)
  - Phase 6: Code Tab Verification (7 items)
  - Phase 7: Test Configuration Verification (7 items)
  - Phase 8: API Testing (4 items)
  - Phase 9: Model Tester Verification (7 items)
  - Phase 10: Documentation Verification (4 items)

- **[common-errors.md](references/common-errors.md)** - 6 common errors + solutions (~200 lines)
  - Error 1: Module not found '@/lib/models/providers'
  - Error 2: Cannot find module '@ai-sdk-tools/store'
  - Error 3: API returns 404 or 500
  - Error 4: Property 'model' does not exist
  - Error 5: Build cache issues / stale code
  - Error 6: Code tab only shows 3 files

- **[examples.md](references/examples.md)** - Complete walkthroughs (~400 lines)
  - Example 1: Install Routing Pattern (simple, 15 min)
  - Example 2: Fix Artifact Table Pattern (complex, 30 min, all 5 issues)

- **[todo-templates.md](references/todo-templates.md)** - TodoWrite templates (~200 lines)
  - Quick Template (10 items) for simple patterns
  - Comprehensive Template (42 items) for artifact patterns
  - Custom Pattern Template (13 items) for building from scratch
  - Usage examples and best practices

## Terminal Testing

```bash
# Test all patterns
node scripts/run-all-tests.mjs

# Test specific pattern
node scripts/run-all-tests.mjs --pattern PATTERN_NAME

# Test specific capability
node scripts/run-all-tests.mjs --capability tools
```

## Layers Documentation

Recent fixes (2026-01-22):
- ✅ Tool call arguments: Now uses `tc.input`
- ✅ Token counting: Proper fallback chain
- ✅ Provider metadata: Fully preserved
- ✅ Perplexity sources: Extracted correctly

All patterns are Layers-compatible by default.

## AI Elements Requirement

This project uses **Vercel AI Elements** as the UI foundation for all AI patterns. AI Elements provides pre-built React components optimized for AI interfaces:

- **Chatbot elements** - Conversation UI, message bubbles, streaming indicators
- **Code elements** - Syntax highlighting, code blocks, copy buttons
- **Voice elements** - Audio recording, transcription UI
- **Workflow utilities** - Loading states, error boundaries, retry logic

### Installation

AI Elements must be installed when setting up the project or adding new patterns:

```bash
npx ai-elements@latest
```

This works seamlessly with shadcn/ui and shares the same design system.

### Usage in Patterns

All artifact patterns (canvas, table, etc.) rely on AI Elements components:
- `<Provider>` from `@ai-sdk-tools/store` for state management
- `<Conversation>`, `<Message>`, `<PromptInput>` from `@/components/ai-elements/`
- Artifact rendering components for dynamic UI generation

When installing external patterns, always ensure AI Elements is available.

## Troubleshooting Decision Tree

**Build Fails?**
→ Check [common-errors.md](references/common-errors.md) Error 1-2

**API Returns Error?**
→ Check [common-errors.md](references/common-errors.md) Error 3-4

**Changes Not Visible?**
→ Check [common-errors.md](references/common-errors.md) Error 5

**Code Tab Empty?**
→ Check [common-errors.md](references/common-errors.md) Error 6

## Quick Commands Reference

```bash
# Install AI Elements
npx ai-elements@latest

# Install pattern
yes y | npx shadcn add 'PATTERN_URL'

# Clean rebuild
rm -rf .next && pnpm dev

# Test pattern
node scripts/run-all-tests.mjs --pattern PATTERN_NAME

# Check registry size
cat registry/PATTERN.json | jq '.files | length'

# Test API
curl -X POST http://localhost:3000/api/playground/CATEGORY/PATTERN \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","prompt":"test"}'
```

## Pattern Installation Checklist

When user says: "Install pattern X"

**Immediately ask:**

```
I'll help you install the pattern. I have two options:

**Option 1: Install from aisdkagents.com**
- Do you have a CLI command from https://www.aisdkagents.com/?
- Example: npx shadcn add 'https://www.aisdkagents.com/pro-registry/...'

**Option 2: Create custom pattern**
- Describe what you want the pattern to do
- I'll research similar patterns and build it

Which option would you like?
```

**If Option 1 (CLI command provided):**

1. Create comprehensive todo list (42 items from [todo-templates.md](references/todo-templates.md))
2. Mark first task in_progress
3. Install AI Elements if needed
4. Run installation command
5. Check for 5 common issues ([fixing-artifacts.md](references/fixing-artifacts.md))
6. Fix each issue (mark todos as you go)
7. Run verification ([verification.md](references/verification.md))
8. Test in browser
9. Test in terminal
10. Mark all todos complete

**If Option 2 (custom pattern):**

1. Ask clarifying questions via AskUserQuestion
2. Research with Context7 for similar patterns
3. Create architecture plan
4. Create todo list for implementation
5. Build files following playground structure
6. Add test configuration
7. Generate registry
8. Verify and test

## Success Criteria

- ✅ ModelSelector appears in pattern UI
- ✅ Users can select from 27+ compatible models
- ✅ API accepts and uses dynamic model selection
- ✅ Pattern works with both direct API and Layers.ai
- ✅ Test configuration exists and passes
- ✅ Code tab displays all pattern files (20+)
- ✅ Pattern tested in browser and works end-to-end
- ✅ All TodoWrite tasks marked complete
- ✅ No console errors in browser or terminal

## Summary

This skill automates pattern installation with:
- 5 common issue fixes
- 10-phase verification (40+ checks)
- 6 error solutions
- 2 complete examples
- 3 TodoWrite templates
- Context7 integration for docs
- Terminal test runner support

Always use TodoWrite to track progress, reference documentation when needed, and verify comprehensively before marking pattern complete.