@oneie/claude 0.4.0 → 0.6.0

package/skills/ai-ui/SKILL.md

@@ -0,0 +1,638 @@
+---
+name: ai-elements
+description: Build advanced AI UIs with agent reasoning, tool visualization, generative UI components, and composable AI Elements for agentic interfaces
+---
+
+# AI Elements - Advanced AI UI Components
+
+Build production-ready agentic interfaces with reasoning traces, tool calls, generative UI, and composable AI Elements.
+
+## Works With
+
+| Skill      | Load when                                                                                 |
+|------------|-------------------------------------------------------------------------------------------|
+| `/react19` | AI Elements are React components — use Actions, `use()`, transitions for streaming.        |
+| `/shadcn`  | Reasoning cards, tool-call blocks, message bubbles compose shadcn primitives + dark theme. |
+| `/ai-sdk`  | Structured tool outputs (`generateObject` + Zod) feed the Tool/Reasoning display shapes.   |
+| `/signal`  | Every tool-call button, approval gate, retry — emit `ui:<surface>:<action>` via `emitClick`. |
+| `/astro`   | Chat pages that host agent UIs — pick hydration (`client:load` for interactive streams).   |
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Build agentic interfaces with tool calling visualization
+- Display AI reasoning traces and chain-of-thought
+- Create generative UI that AI can dynamically render
+- Implement multi-step workflows with progress indicators
+- Show tool execution states and approvals
+- Build chat interfaces with advanced agent features
+
+## Core Concepts
+
+### 1. Agentic UI
+Interfaces that visualize autonomous agent behavior:
+- **Tool Calls**: Display function calls and results
+- **Reasoning Traces**: Show AI thinking process
+- **Multi-Step Workflows**: Visualize agent planning
+- **Approval Gates**: Request human confirmation
+
+### 2. Generative UI
+AI generates structured UI components dynamically:
+- **Component Registry**: Map AI output to React components
+- **Type-Safe Rendering**: Validate AI-generated structures
+- **Dynamic Charts/Tables**: Render data visualizations
+- **Interactive Elements**: Buttons, forms, products
+
+### 3. AI Elements
+Composable primitives for AI interfaces:
+- **Conversation**: Auto-scrolling chat container
+- **Message**: Formatted message bubbles
+- **Tool**: Collapsible tool call display
+- **Reasoning**: Expandable thinking traces
+- **Loader/Shimmer**: Loading states
+
+## Existing AI Components
+
+### Chat Components
+
+**ChatClient** (`/web/src/components/ai/ChatClient.tsx`)
+```tsx
+// Premium chat with agent features
+import { ChatClient } from '@/components/ai/ChatClient';
+
+<ChatClient
+  client:only="react"
+  apiEndpoint="/api/chat"
+  initialMessages={[]}
+/>
+```
+
+**Features:**
+- Agent reasoning visualization
+- Tool call display
+- Model selector (50+ models)
+- Extended message types (text, reasoning, tool_call, ui)
+- Streaming support
+- Premium indicators
+
+### Tool System
+
+**ToolSelector** (`/web/src/components/ai/ToolSelector.tsx`)
+```tsx
+import { ToolSelector } from '@/components/ai/ToolSelector';
+
+const tools = [
+  { id: 'web_search', name: 'Web Search', icon: <Search />, description: '...' },
+  { id: 'google_sheets', name: 'Google Sheets', icon: <FileSpreadsheet />, ... },
+  { id: 'weather', name: 'Weather', icon: <CloudSun />, ... },
+  { id: 'create_chart', name: 'Create Chart', icon: <Table2 />, ... },
+];
+
+<ToolSelector
+  selectedTool={selectedTool}
+  onToolSelect={handleToolSelect}
+/>
+```
+
+**ToolCall** (`/web/src/components/ai/ToolCall.tsx`)
+Displays tool execution with states:
+- `input-streaming`: Tool input being generated
+- `input-available`: Ready to execute
+- `approval-requested`: Awaiting human approval
+- `output-available`: Completed successfully
+- `output-error`: Execution failed
+
+### Reasoning Components
+
+**Reasoning** (`/web/src/components/ai/elements/reasoning.tsx`)
+```tsx
+import { Reasoning, ReasoningTrigger, ReasoningContent } from '@/components/ai/elements/reasoning';
+
+<Reasoning isStreaming={isLoading} open={showReasoning}>
+  <ReasoningTrigger />
+  <ReasoningContent>
+    {reasoningText}
+  </ReasoningContent>
+</Reasoning>
+```
+
+**Features:**
+- Auto-opens when streaming starts
+- Auto-closes after completion (with delay)
+- Duration tracking
+- Collapsible/expandable
+- Markdown rendering with Streamdown
+
+**Simple Reasoning** (`/web/src/components/ai/Reasoning.tsx`)
+```tsx
+import { Reasoning } from '@/components/ai/Reasoning';
+
+const steps = [
+  { step: 1, title: 'Analyzing request', description: '...', completed: true },
+  { step: 2, title: 'Calling web search', description: '...', completed: true },
+  { step: 3, title: 'Generating response', description: '...', completed: false },
+];
+
+<Reasoning steps={steps} />
+```
+
+## Generative UI Pattern
+
+### Architecture
+
+```
+AI Model                  GenerativeUIRenderer              React Components
+────────                  ────────────────────             ─────────────────
+Generate JSON      →      Parse & Validate          →      Render Component
+{                         switch(component)                <DynamicCard />
+  component: "card",      case "card":                     <DynamicTable />
+  data: {...}             return <DynamicCard />           <DynamicChart />
+}                                                          etc.
+```
+
+### GenerativeUIRenderer
+
+**Main Renderer** (`/web/src/components/generative-ui/GenerativeUIRenderer.tsx`)
+```tsx
+import { GenerativeUIRenderer } from '@/components/generative-ui/GenerativeUIRenderer';
+
+interface UIPayload {
+  component: 'chart' | 'table' | 'card' | 'form' | 'list' | 'timeline' | 'button' | 'product' | 'checkout';
+  data: any;
+  layout?: any;
+}
+
+const payload: UIPayload = {
+  component: 'card',
+  data: {
+    title: 'Weather Update',
+    description: 'Current conditions',
+    content: '72°F, Sunny',
+  },
+};
+
+<GenerativeUIRenderer payload={payload} />
+```
+
+### Available Dynamic Components
+
+#### DynamicCard
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'card',
+  data: {
+    title: 'Title',
+    description: 'Subtitle',
+    content: 'Content here',
+    actions: [
+      { label: 'View', variant: 'default' },
+      { label: 'Share', variant: 'outline' },
+    ],
+  },
+}} />
+```
+
+#### DynamicTable
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'table',
+  data: {
+    headers: ['Name', 'Price', 'Stock'],
+    rows: [
+      ['Product A', '$29.99', '50'],
+      ['Product B', '$49.99', '23'],
+    ],
+  },
+}} />
+```
+
+#### DynamicChart
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'chart',
+  data: {
+    type: 'bar' | 'line' | 'pie',
+    data: [
+      { name: 'Jan', value: 100 },
+      { name: 'Feb', value: 150 },
+    ],
+    xKey: 'name',
+    yKey: 'value',
+  },
+}} />
+```
+
+#### DynamicList
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'list',
+  data: {
+    items: ['Item 1', 'Item 2', 'Item 3'],
+    ordered: false,
+  },
+}} />
+```
+
+#### DynamicForm
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'form',
+  data: {
+    fields: [
+      { name: 'email', type: 'email', label: 'Email', required: true },
+      { name: 'message', type: 'textarea', label: 'Message' },
+    ],
+    submitLabel: 'Send',
+  },
+}} />
+```
+
+#### DynamicProduct
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'product',
+  data: {
+    title: 'Premium Coffee Mug',
+    description: 'Hand-crafted ceramic mug',
+    price: 29.99,
+    originalPrice: 49.99,
+    image: '/mug.jpg',
+    rating: 4.5,
+    reviewCount: 120,
+    stock: 50,
+    badge: 'Bestseller',
+    category: 'Kitchen',
+  },
+  onAddToCart: (data, quantity) => {
+    // Handle cart logic
+  },
+}} />
+```
+
+**Features:**
+- Stripe checkout integration
+- Quantity selector
+- Stock tracking
+- Reviews and ratings
+- Discount badges
+- Auto-checkout flow
+
+#### DynamicCheckout
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'checkout',
+  data: {
+    items: [
+      { title: 'Product', price: 29.99, quantity: 2 },
+    ],
+    total: 59.98,
+  },
+}} />
+```
+
+#### DynamicTimeline
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'timeline',
+  data: {
+    events: [
+      { date: '2024-01-01', title: 'Event 1', description: '...' },
+      { date: '2024-01-15', title: 'Event 2', description: '...' },
+    ],
+  },
+}} />
+```
+
+#### DynamicButton
+```tsx
+<GenerativeUIRenderer payload={{
+  component: 'button',
+  data: {
+    label: 'Click Me',
+    variant: 'default' | 'outline' | 'destructive',
+    onClick: () => console.log('clicked'),
+  },
+}} />
+```
+
+## AI Elements Library
+
+### Conversation Elements
+
+**Conversation** (`/web/src/components/ai/elements/conversation.tsx`)
+```tsx
+import { Conversation, ConversationContent, ConversationScrollButton } from '@/components/ai/elements/conversation';
+
+<Conversation>
+  <ConversationContent>
+    {messages.map(msg => <Message key={msg.id} {...msg} />)}
+  </ConversationContent>
+  <ConversationScrollButton />
+</Conversation>
+```
+
+**Features:**
+- Auto-scrolling
+- Scroll-to-bottom button
+- Virtualization support
+
+### Message Elements
+
+**Message** (`/web/src/components/ai/elements/message.tsx`)
+```tsx
+import { Message, MessageContent, MessageActions, MessageAction } from '@/components/ai/elements/message';
+
+<Message role="assistant">
+  <MessageContent>
+    {content}
+  </MessageContent>
+  <MessageActions>
+    <MessageAction icon={<Copy />} onClick={handleCopy} />
+    <MessageAction icon={<ThumbsUp />} onClick={handleLike} />
+  </MessageActions>
+</Message>
+```
+
+### Tool Elements
+
+**Tool** (`/web/src/components/ai/elements/tool.tsx`)
+```tsx
+import { Tool, ToolHeader, ToolContent } from '@/components/ai/elements/tool';
+
+<Tool>
+  <ToolHeader
+    title="web_search"
+    type="tool-call"
+    state="output-available"
+  />
+  <ToolContent>
+    {toolResult}
+  </ToolContent>
+</Tool>
+```
+
+**States:**
+- `input-streaming`: Pending
+- `input-available`: Running
+- `approval-requested`: Awaiting Approval
+- `approval-responded`: Responded
+- `output-available`: Completed
+- `output-error`: Error
+- `output-denied`: Denied
+
+### Model Selector
+
+**ModelSelector** (`/web/src/components/ai/elements/model-selector.tsx`)
+```tsx
+import {
+  ModelSelector,
+  ModelSelectorTrigger,
+  ModelSelectorContent,
+  ModelSelectorList,
+  ModelSelectorGroup,
+  ModelSelectorItem,
+  ModelSelectorLogo,
+} from '@/components/ai/elements/model-selector';
+
+<ModelSelector>
+  <ModelSelectorTrigger>
+    <ModelSelectorLogo model="claude-3-5-sonnet" />
+    Claude 3.5 Sonnet
+  </ModelSelectorTrigger>
+  <ModelSelectorContent>
+    <ModelSelectorList>
+      <ModelSelectorGroup heading="Anthropic">
+        <ModelSelectorItem value="claude-3-5-sonnet">
+          Claude 3.5 Sonnet
+        </ModelSelectorItem>
+      </ModelSelectorGroup>
+    </ModelSelectorList>
+  </ModelSelectorContent>
+</ModelSelector>
+```
+
+### Prompt Input
+
+**PromptInput** (`/web/src/components/ai/elements/prompt-input.tsx`)
+```tsx
+import { PromptInput, PromptInputSpeechButton } from '@/components/ai/elements/prompt-input';
+
+<PromptInput
+  value={input}
+  onChange={handleChange}
+  onSubmit={handleSubmit}
+  disabled={isLoading}
+>
+  <PromptInputSpeechButton />
+</PromptInput>
+```
+
+### Loading Elements
+
+**Loader** (`/web/src/components/ai/elements/loader.tsx`)
+```tsx
+import { Loader } from '@/components/ai/elements/loader';
+
+<Loader />
+```
+
+**Shimmer** (`/web/src/components/ai/elements/shimmer.tsx`)
+```tsx
+import { Shimmer } from '@/components/ai/elements/shimmer';
+
+<Shimmer />
+```
+
+### Task & Queue Elements
+
+**Task** (`/web/src/components/ai/elements/task.tsx`)
+Multi-step task visualization
+
+**Queue** (`/web/src/components/ai/elements/queue.tsx`)
+Task queue management
+
+**Checkpoint** (`/web/src/components/ai/elements/checkpoint.tsx`)
+Workflow checkpoints
+
+## Complete Example: Agentic Chat Interface
+
+```tsx
+import { useState } from 'react';
+import { useChat } from 'ai/react';
+import { ChatClient } from '@/components/ai/ChatClient';
+import { ToolSelector } from '@/components/ai/ToolSelector';
+import { Reasoning } from '@/components/ai/elements/reasoning';
+import { Tool } from '@/components/ai/elements/tool';
+import { GenerativeUIRenderer } from '@/components/generative-ui/GenerativeUIRenderer';
+
+export function AgenticChat() {
+  const [selectedTool, setSelectedTool] = useState('none');
+  const {
+    messages,
+    input,
+    handleInputChange,
+    handleSubmit,
+    isLoading,
+  } = useChat({
+    api: '/api/agent-chat',
+    body: {
+      tool: selectedTool,
+    },
+  });
+
+  return (
+    <div className="flex flex-col h-screen">
+      {/* Tool Selector */}
+      <div className="p-4 border-b">
+        <ToolSelector
+          selectedTool={selectedTool}
+          onToolSelect={(tool) => setSelectedTool(tool.id)}
+        />
+      </div>
+
+      {/* Messages */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-4">
+        {messages.map((msg) => (
+          <div key={msg.id}>
+            {/* Regular message */}
+            {msg.type === 'text' && (
+              <div className={msg.role === 'user' ? 'text-right' : ''}>
+                <div className="inline-block px-4 py-2 rounded-lg bg-muted">
+                  {msg.content}
+                </div>
+              </div>
+            )}
+
+            {/* Reasoning trace */}
+            {msg.type === 'reasoning' && (
+              <Reasoning isStreaming={isLoading}>
+                {msg.content}
+              </Reasoning>
+            )}
+
+            {/* Tool call */}
+            {msg.type === 'tool_call' && (
+              <Tool>
+                <ToolHeader
+                  title={msg.toolName}
+                  type="tool-call"
+                  state={msg.state}
+                />
+                <ToolContent>
+                  {JSON.stringify(msg.result, null, 2)}
+                </ToolContent>
+              </Tool>
+            )}
+
+            {/* Generative UI */}
+            {msg.type === 'ui' && (
+              <GenerativeUIRenderer payload={msg.payload} />
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Input */}
+      <form onSubmit={handleSubmit} className="p-4 border-t">
+        <input
+          value={input}
+          onChange={handleInputChange}
+          disabled={isLoading}
+          className="w-full px-4 py-2 border rounded-lg"
+          placeholder="Ask anything..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+1. **Component Composition**: Use AI Elements as building blocks
+2. **Type Safety**: Validate AI-generated UI payloads
+3. **Progressive Disclosure**: Show reasoning/tools on demand
+4. **Streaming Support**: Display partial results in real-time
+5. **Error Handling**: Show friendly errors for failed tools
+6. **Accessibility**: ARIA labels for tool states
+7. **Loading States**: Use Shimmer for skeleton screens
+
+## Integration with Convex
+
+Store agent traces and tool calls:
+
+```typescript
+// Store reasoning trace
+await ctx.db.insert('events', {
+  groupId: user.groupId,
+  type: 'agent_reasoning',
+  actorId: user._id,
+  targetId: conversationId,
+  timestamp: Date.now(),
+  metadata: {
+    steps: reasoningSteps,
+    duration: 2.5,
+  },
+});
+
+// Store tool call
+await ctx.db.insert('events', {
+  groupId: user.groupId,
+  type: 'tool_executed',
+  actorId: user._id,
+  targetId: conversationId,
+  timestamp: Date.now(),
+  metadata: {
+    toolName: 'web_search',
+    input: { query: 'AI news' },
+    output: { results: [...] },
+    duration: 1.2,
+  },
+});
+```
+
+## Common Patterns
+
+### Pattern 1: Tool-Enhanced Chat
+```tsx
+<ChatClient withTools={true} />
+```
+
+### Pattern 2: Reasoning-First Agent
+```tsx
+<Reasoning isStreaming={isLoading} defaultOpen={true}>
+  {thinkingProcess}
+</Reasoning>
+```
+
+### Pattern 3: Generative UI Response
+```tsx
+{message.type === 'ui' && (
+  <GenerativeUIRenderer payload={message.payload} />
+)}
+```
+
+### Pattern 4: Multi-Step Workflow
+```tsx
+<Task steps={workflowSteps} currentStep={2} />
+```
+
+## Related Files
+
+- AI Components: `/web/src/components/ai/`
+- AI Elements: `/web/src/components/ai/elements/`
+- Generative UI: `/web/src/components/generative-ui/`
+- Chat API: `/web/src/pages/api/chat.ts`
+
+## Token Budget
+
+- Metadata: ~100 tokens
+- Instructions: ~2800 tokens
+- Examples: ~1500 tokens
+- Total: ~4400 tokens
+
+---
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-12
+**Maintained By**: AI Team