skills

Overview and router for assistant-ui, the React library for building AI chat interfaces from composable primitives and a styled elements catalog. Use for high-level, cross-cutting, or architecture questions: choosing packages, picking a runtime, or understanding the layers (elements, primitives, the aui client with AuiConfig and AuiProvider, the runtime, adapters) and the message model. Covers `@assistant-ui/react` 0.15.x, `@assistant-ui/ai-sdk` for AI SDK v7 (`useChatRuntime`), `@assistant-ui/core`, `@assistant-ui/store`, `assistant-stream`, `assistant-cloud`, the LangGraph, LangChain, Google ADK, A2A, AG-UI, Eve, OpenCode, and Pi adapters, the `@assistant-ui/react-native` and `@assistant-ui/react-ink` bindings, and the `useAui`, `useAuiState`, and `useAuiEvent` hooks. For a specific area route to a focused sibling instead: setup, elements, primitives, runtime, tools, generative-ui, streaming, cloud, thread-list, copilots, markdown, react-mcp, observability, react-native, ink, or update.

Adds AssistantCloud backed persistence, authorization, and telemetry to assistant-ui apps. Use when wiring cross-session thread and message history, multi-device chat, message feedback, file uploads, or auth: passing `cloud` to `useChatRuntime` from `@assistant-ui/ai-sdk`, `AISDKThreads({ cloud })` for `AuiConfig` hosts, the `useCloudChat`/`useThreads` hooks from `@assistant-ui/cloud-ai-sdk`, or `cloud` on `useLangGraphRuntime`. Covers constructing `AssistantCloud` with `authToken` (JWT), `apiKey` plus `userId`/`workspaceId` (server-side only), or `anonymous`; Clerk, Auth0, Supabase, and Firebase integrations and a backend token endpoint; the `cloud.threads`, `cloud.files`, `cloud.runs`, and `cloud.telemetry` client surface; and a custom `ThreadHistoryAdapter` on `CloudMessagePersistence`. Route here for threads that do not persist, 401s against the cloud API, or feedback buttons that do not save. For the `<ThreadList />` sidebar UI use thread-list; for the general adapter contracts use runtime.

Grounds an assistant in your app with assistant-ui copilots. Use when steering behavior with useAssistantInstructions, feeding send-time app state through useAssistantContext({ getContext }), exposing components with makeAssistantVisible(Component, { clickable, editable }), giving the model two-way component state through interactables (unstable_useInteractable for app-scoped panels, unstable_interactableTool inside defineToolkit for thread-scoped artifacts, mounted via AuiConfig({ unstable_interactables: unstable_Interactables() })), registering instructions and tools with aui.modelContext.register, or bridging model context across an iframe with AssistantFrameProvider and useAssistantFrameHost. Legacy Interactables(), useAssistantInteractable, and useInteractableState are deprecated in favor of the unstable_ API. Reach for this when the assistant should read the page, click or edit UI, or update component state. For LLM tools use tools; for runtime and thread state use runtime.

Installs and customizes assistant-ui elements, the styled shadcn-style component catalog served from the r.assistant-ui.com registry through `npx assistant-ui@latest add <item>`. Use when adding a prebuilt chat surface or widget (Thread, ThreadList, AssistantModal, AssistantSidebar, ToolFallback, ToolGroup, MarkdownText, Reasoning, Sources, Attachment, ModelSelector, Voice orb, McpConfig) or one of the 120 standalone elements (approval card, agent plan, code diff, data table, chart, and so on), choosing between runtime-connected `<name>.aui.tsx` files and props-driven standalone files, overriding Thread slots through the `components` prop, editing the copied source under `components/assistant-ui/elements/`, or picking the Radix versus Base UI flavor in `components.json`. Route here when an import from `@/components/assistant-ui/...` fails, an element renders unstyled, or the CLI installs the wrong flavor. For unstyled building blocks use primitives; for the CLI scaffold itself use setup.

Lets the model compose interfaces at runtime from a component vocabulary instead of one hand-written component per tool, and covers every generative UI pattern in the framework. Use for the model-driven present tool: JSONGenerativeUI, defaultGenerativeUILibrary, and present({ display }) from @assistant-ui/react-generative-ui, registered through AuiConfig({ tools: Tools({ toolkit }) }). Also covers the backend-driven MessagePrimitive.GenerativeUI primitive and its component allowlist, the Slack Block Kit and Microsoft Teams Adaptive Card renderers and their action decoders, A2UI surfaces over AG-UI, and the third-party OpenUI integration. Route here when the model should design its own layout rather than fill one you wrote, when an unknown $type or component name throws or silently renders nothing, or when a generative UI tree needs to post to Slack or Teams or paint an A2UI surface. For a widget tied to one tool call you already know about, use tool-ui in the tools skill instead.

Builds terminal chat UIs with @assistant-ui/react-ink and ANSI markdown with @assistant-ui/react-ink-markdown. Use when scaffolding `create --ink`, mounting `AssistantRuntimeProvider` around `useChatRuntime`, composing `ThreadPrimitive`, `ComposerPrimitive`, `MessagePrimitive`, `LoadingPrimitive`, `TextInput`, thread history, attachments, notifications, and terminal keyboard navigation, or when a chat needs grapheme safe editing, multiline display columns, an absolute backend URL, local file storage, or a custom `RemoteThreadListAdapter`. Route terminal markdown, tool output, message rendering, and Ink focus problems here. For browser application setup, web elements, and the standard web runtime, use [setup](../setup/SKILL.md).

Renders assistant message text as markdown in assistant-ui. Use when wiring MarkdownTextPrimitive or the markdown-text element into MessagePrimitive.Parts, installing Shiki or Prism highlighting, adding KaTeX math or Mermaid diagrams, normalizing model-produced math delimiters, or choosing StreamdownTextPrimitive for block-aware streaming with optional code, math, Mermaid, and CJK plugins. Covers defer and smooth parsing behavior, code block overrides, and stream completion. For the surrounding unstyled message composition use primitives, and for installing or editing a styled renderer use elements.

Instruments assistant-ui AI SDK backend routes with Langfuse, LangSmith, or Helicone, and renders independent trace data with the experimental @assistant-ui/react-o11y SpanResource and SpanPrimitive APIs. Use it when traces are missing, serverless spans are dropped, an AI SDK call needs provider metadata, Helicone is not proxying a provider, or a trace tree or timeline needs rendering. For streaming transport use streaming, for initial application wiring use setup, for Assistant Cloud persistence use cloud, and for copied styled trace UI use elements.

Builds and customizes assistant-ui chat UI from composable, unstyled @assistant-ui/react primitives: ThreadPrimitive, ComposerPrimitive (with Unstable_TriggerPopover for mentions and slash commands), MessagePrimitive and MessagePartPrimitive, ActionBarPrimitive, BranchPickerPrimitive, AttachmentPrimitive, ErrorPrimitive, AssistantModalPrimitive, ChainOfThoughtPrimitive, SelectionToolbarPrimitive, SuggestionPrimitive, QueueItemPrimitive, and the ThreadList primitives. Use when assembling or styling a custom Thread, Composer, message list, action bar, branch picker, or suggestion grid; wiring composer input, dictation, quoting, or attachments; or handling editing, branching, virtualization, scrolling, or chain of thought UI. Covers MessagePrimitive.Parts render functions per part type, groupPartByType, AuiIf in selector form, and the unstyled gotchas (AssistantRuntimeProvider, className). For prebuilt UI use setup, for the styled catalog use elements, for multi-thread sidebars use thread-list.

Adds user managed browser MCP servers to assistant-ui with `@assistant-ui/react-mcp`. Use when mounting `McpManagerResource`, declaring `defineConnector` presets, persisting custom servers and OAuth state, composing `McpManagerPrimitive`, `McpServerPrimitive`, `McpAddFormPrimitive`, or `McpElicitationPrimitive`, handling an OAuth callback, browsing MCP resources, or diagnosing missing server tools, connection failures, and OAuth redirects. This covers end user chosen servers, not application owned backend MCP tools. For those use tools; for the chat runtime use runtime; for the copied dialog use elements.

Build assistant-ui chat experiences for Expo and bare React Native with `@assistant-ui/react-native` and `@assistant-ui/ai-sdk`. Use when setting up an absolute mobile chat endpoint, `AssistantRuntimeProvider`, `useChatRuntime`, `AssistantChatTransport`, native `ThreadPrimitive`, `ComposerPrimitive`, `MessagePrimitive`, thread lists, attachments, React Native styles, `Metro` `withAui` for a `"use generative"` toolkit, local or remote thread adapters, or migrating a web chat surface to iOS and Android. Route here when a relative API URL fails on device, a native primitive lacks runtime state, `Metro` does not compile a toolkit, or web Elements are being used in a native app. Route web setup and DOM primitive work to `../setup/SKILL.md` and `../primitives/SKILL.md`.

Guide to the assistant-ui runtime system, the state and action layer behind every chat surface. Use when creating a runtime (useLocalRuntime with a ChatModelAdapter, useExternalStoreRuntime for Redux or Zustand backed stores, useRemoteThreadListRuntime, useCloudThreadListRuntime, useAssistantTransportRuntime), wiring AssistantRuntimeProvider, or reading and mutating thread, message, composer, and attachment state. Covers useAui, useAuiState, and useAuiEvent with the stable selector rule, the scope accessors (aui.thread, aui.message, aui.composer, and siblings), the AuiConfig plus AuiProvider grammar, RuntimeCapabilities, and the attachment, speech, dictation, feedback, suggestion, and history adapters. Route here for a provider error ('Cannot read property of undefined'), a removed v0.12 hook import, an infinite re-render from an object literal selector, or state not updating. For multi-thread list UI use thread-list instead; for toolkit definitions and tool call UI use tools instead.

Installs and configures assistant-ui with the `assistant-ui` CLI (`create`, `init`, `add`, `update`, `upgrade`, `codemod`, `doctor`, `info`, `mcp`, `agent`) and picks the runtime adapter for a backend. Use for first-time install (`npx assistant-ui@latest create`, templates, `--example` scaffolds), adding to an existing Next.js app (`init`), or keeping an install current. Covers the runtime hook per backend: `useChatRuntime` (AI SDK v7), `useLangGraphRuntime`, `useStreamRuntime` (LangChain), `useAdkRuntime`, `useA2ARuntime`, `useAgUiRuntime`, `useEveAgentRuntime`, `useOpenCodeRuntime`, `useLocalRuntime`, `useExternalStoreRuntime`, `useDataStreamRuntime`, and `useAssistantTransportRuntime`, plus wiring guides for Mastra, Cloudflare Agents, Claude Managed Agents, LLM gateways, and Electron, the Expo (`--native`) and React Ink (`--ink`) scaffolds, and the hosted MCP docs server. Once a runtime exists, use elements for the styled Thread, runtime for hooks and adapters, and update for a deep migration.

Streaming wire protocols and backend helpers for assistant-ui, built on the assistant-stream package. Use when building a custom streaming endpoint outside the Vercel AI SDK with createAssistantStreamResponse, createAssistantStream, or createAssistantStreamController; choosing between the Data Stream protocol (useDataStreamRuntime, DataStreamEncoder, DataStreamDecoder) and the Assistant Transport protocol (AssistantTransportEncoder, AssistantTransportDecoder); decoding a response with AssistantStream.fromResponse, UIMessageStreamDecoder, or PlainTextDecoder; or wiring resumable streams through assistant-stream/resumable with in-memory, Redis, or ioredis stores. Route here for wire level symptoms: an unexpected part-start or text-delta shape, a tool call that never settles, a part that silently drops, a Content-Type mismatch, or a reload that cannot resume a response. For runtime hooks use runtime; for AI SDK route handlers without a custom protocol use setup; for cloud persistence use cloud.

Builds and customizes multiple conversation lists in assistant-ui with the runtime connected ThreadList and ThreadListSidebar elements, ThreadListPrimitive, ThreadListItemPrimitive, ThreadListItemMorePrimitive, useAui, useAuiState, and threads.selectionChanged. Use when adding a conversation sidebar, switching, archiving, renaming, deleting, searching, grouping, paginating, or persisting threads, or when thread state is stale after authentication. Covers AssistantCloud, RemoteThreadListRuntime, and ExternalStoreThreadListAdapter. Use runtime for the active conversation runtime, cloud for managed authentication and persistence, and elements for registry installation and styling.

Defines model-callable tools and renders their calls in assistant-ui. The authoring model: a "use generative" file whose default export is defineToolkit({...}), compiled by withAui from @assistant-ui/next, aui() from @assistant-ui/vite, or withAui from @assistant-ui/metro, mounted with AuiConfig({ tools: Tools({ toolkit }) }), and exposed to the model with new AISDKToolkit({ toolkit }).tools({ frontend }). Covers the tool kinds (backend, "use client" frontend, humanTool(), providerTool(), externalTool(), stubTool(), defineMcpToolkit()), render and display, ToolCallMessagePartProps, approval gates, MCP servers, MCP Apps, WebMCP, and sub-agent messages. Reach for it when a tool is never called, a tool UI does not render, a frontend result never reaches the model, humanTool() throws at runtime, or an approval gate cannot be answered. For model-composed UI use generative-ui, for MCP servers users add in the browser use react-mcp, and for the styled ToolFallback and ToolGroup use elements.

Upgrades an existing assistant-ui application and applies the migrations needed to reach the current AI SDK v7 and assistant-ui 0.15.x lines. Use when updating, bumping, or migrating @assistant-ui/react, @assistant-ui/ai-sdk, the older @assistant-ui/react-ai-sdk alias, ai, or @ai-sdk/react, or when an upgrade exposes removed hooks, scope accessor calls, provider configuration, registry paths, event names, legacy interactables, or tool registrations. Start here for an existing project, post-update type failures, package compatibility, CLI codemods, and version-specific migration order. For a first install or a new project use setup; for authoring a runtime without an upgrade use runtime.