update
assistant-ui/skills
Upgrade assistant-ui and AI SDK packages with automatic breaking-change detection and migration routing.
What is update?
Detects installed versus latest versions of @assistant-ui/react, @assistant-ui/react-ai-sdk, ai, and @ai-sdk/react, then routes through version-specific breaking-change migrations. Use when updating packages, resolving peer-dependency conflicts, or applying renamed APIs after a version jump.
- Detects current and latest package versions via npm ls and npm view
- Routes migrations based on version gaps (AI SDK v4/v5→v6, assistant-ui 0.8.x→0.14.x)
- Applies breaking-change mappings: useAssistantApi→useAui, runtime.threadList→runtime.threads, ThreadPrimitive.ViewportSlack removal, components prop→children render functions, toDataStreamResponse→toUIMessageStreamResponse, maxSteps→stopWhen: stepCountIs(n)
- Executes package updates and type verification with npx tsc --noEmit
- Prioritizes AI SDK migration before assistant-ui to resolve peer dependencies
How to install update
npx skills add https://github.com/assistant-ui/skills --skill update- Existing assistant-ui project (not a fresh scaffold)
- npm or pnpm installed and configured
- Node.js environment with TypeScript support
How to use update
- 1.Run npm ls to check current versions of @assistant-ui/react, @assistant-ui/react-ai-sdk, ai, and @ai-sdk/react
- 2.Compare against latest versions using npm view for each package
- 3.If AI SDK < 6.0.0, follow AI SDK v6 migration guide first
- 4.If assistant-ui < 0.14.0, apply breaking-change mappings from references (useAssistantApi→useAui, runtime.threadList→runtime.threads, etc.)
- 5.Run pnpm add @latest or npm install @latest for all packages together
- 6.Execute npx tsc --noEmit to verify type compliance and catch migration errors
Use cases
- Upgrading @assistant-ui/react from 0.8.x to 0.14.x with automatic API renaming
- Migrating AI SDK from v4/v5 to v6 before updating assistant-ui packages
- Resolving peer-dependency conflicts when multiple packages are outdated
- Applying post-upgrade type fixes and verifying breaking-change compliance
- Updating projects that hit renamed APIs like useAssistantApi or runtime.threadList
- Developers maintaining existing assistant-ui projects
- Teams upgrading across major version boundaries
- Engineers resolving peer-dependency or type-check failures after package updates
update FAQ
Use update for existing projects that need version bumps or migrations. Use setup for first-time installs or fresh scaffolds.
Yes. If ai < 6.0.0, migrate AI SDK first—it is required for @assistant-ui/react-ai-sdk >= 1.0 and resolves peer dependencies.
Update all packages together (pnpm add @latest or npm install @latest) and check the breaking-changes reference table for version compatibility.
The skill routes to version-specific migration guides. Common changes: useAssistantApi→useAui, runtime.threadList→runtime.threads, components prop→children render functions, ThreadPrimitive.ViewportSlack removal.
Run npx tsc --noEmit to type-check, then pnpm build or npm run build to ensure no runtime errors.
Full instructions (SKILL.md)
Source of truth, from assistant-ui/skills.
name: update description: "Upgrades an existing assistant-ui project to current releases and executes the resulting migrations. Use when the user wants to update, upgrade, bump, or migrate @assistant-ui/react, @assistant-ui/react-ai-sdk, ai, or @ai-sdk/react, hits peer-dependency conflicts or post-upgrade type errors, or must apply renamed APIs after a version jump. Detects installed versus latest versions via npm ls / npm view, then routes through breaking-change references for each jump (AI SDK v4/v5 to v6; assistant-ui 0.8.x to 0.14.x): useAssistantApi to useAui, runtime.threadList to runtime.threads, ThreadPrimitive.ViewportSlack removal, the primitives components prop to children render functions, toDataStreamResponse to toUIMessageStreamResponse, maxSteps to stopWhen: stepCountIs(n). Runs npx assistant-ui@latest upgrade, pnpm/npm add @latest, and npx tsc --noEmit to verify. For a first-time install or fresh scaffold (not an upgrade) use setup instead." license: MIT
assistant-ui Update
Always verifies against npm ground truth and GitHub commits.
References
- ./references/ai-sdk-v6.md -- AI SDK v4/v5 → v6 migration (complete guide)
- ./references/assistant-ui.md -- assistant-ui version migrations
- ./references/breaking-changes.md -- Quick reference table
Phase 1: Detect Versions
Get Ground Truth
npm ls @assistant-ui/react @assistant-ui/react-ai-sdk ai @ai-sdk/react 2>/dev/null
npm view @assistant-ui/react version
npm view @assistant-ui/react-ai-sdk version
npm view ai version
Version Analysis
Current latest: @assistant-ui/react 0.14.x, @assistant-ui/react-ai-sdk 1.3.x, assistant-stream 0.3.x.
| Package | Check For |
|---|---|
ai | < 6.0.0 → needs AI SDK v6 migration |
@assistant-ui/react | < 0.14.0 → primitives components prop replaced by children render functions; deprecated hooks/aliases removed |
@assistant-ui/react | < 0.13.0 → ThreadPrimitive.ViewportSlack removed (top-anchor changes) |
@assistant-ui/react | < 0.12.0 → unified state API (useAui/useAuiState/useAuiEvent/AuiIf) |
@assistant-ui/react | < 0.11.0 → runtime rearchitecture |
@assistant-ui/react | < 0.10.0 → ESM only |
@assistant-ui/react | < 0.8.0 → UI split (shadcn registry) |
@assistant-ui/react-ai-sdk | < 1.0.0 → needs AI SDK v6 first |
Phase 2: Route to Migration
AI SDK < 6.0.0?
├─ Yes → See ./references/ai-sdk-v6.md
└─ No
└─ assistant-ui outdated?
├─ Yes → See ./references/assistant-ui.md
└─ No → Already up to date
Migration Order
- AI SDK first (if < 6.0.0) - Required for @assistant-ui/react-ai-sdk >= 1.0
- assistant-ui second - Apply breaking changes for version jump
- Verify - Type check, build, test
Phase 3: Execute
Update Packages
pnpm add @assistant-ui/react@latest @assistant-ui/react-ai-sdk@latest ai@latest @ai-sdk/react@latest
npm install @assistant-ui/react@latest @assistant-ui/react-ai-sdk@latest ai@latest @ai-sdk/react@latest
Apply Migrations
Based on version jump, apply relevant migrations from references.
Verify
npx tsc --noEmit
pnpm build
Troubleshooting
"Peer dependency conflict"
- Update all packages together
- Check version compatibility in ./references/breaking-changes.md
Type errors after upgrade
- Consult breaking changes reference
- Check specific migration guide
Runtime errors
- Verify API patterns match new version
- Check for renamed/moved APIs
Related skills
More from assistant-ui/skills and the wider catalog.
assistant-ui
React library for building AI chat interfaces with composable primitives and pluggable runtimes.
cloud
Cross-session thread/message persistence and authorization for assistant-ui apps with cloud storage and file uploads.
copilots
Grounding an assistant in your app with assistant-ui copilots (@assistant-ui/react). Use when steering assistant behavior with useAssistantInstructions, feeding lazy app-state context via useAssistantContext({ getContext }), exposing rendered components with makeAssistantVisible(Component, { clickable, editable }), building two-way interactable state with useAssistantInteractable and Interactables(), or registering instructions and tools imperatively through useAui().modelContext().register({ getModelContext }). Reach for this when the assistant should read the current page, click or edit UI, or read and update component state through auto-generated update_{name} tools. For LLM tools and tool-call UI use the tools skill; for runtime and thread state use the runtime skill.
markdown
Render and customize assistant message text as markdown in assistant-ui. Use when displaying model output as formatted markdown with MarkdownTextPrimitive from @assistant-ui/react-markdown wired into the MessagePrimitive.Parts text branch, configuring remarkPlugins (remark-gfm, remark-math) and rehypePlugins (rehype-katex), or memoizing components with unstable_memoizeMarkdownComponents. Covers code-block syntax highlighting via react-shiki or react-syntax-highlighter registered as SyntaxHighlighter in components/componentsByLanguage, LaTeX math rendering with KaTeX, Mermaid diagrams gated on stream completion, custom math delimiters via preprocess, and the StreamdownTextPrimitive alternative from @assistant-ui/react-streamdown with built-in Shiki/KaTeX/Mermaid and block streaming. For general chat UI composition route to primitives.
tool-ui
Find, install, configure, and integrate Tool UI components in React apps using shadcn registry entries, compatibility checks, scaffolded runtime wiring, toolkit setup with assistant-ui, and troubleshooting workflows. Use when developers ask to add one or more Tool UI components, choose components for a use case, verify compatibility, wire a toolkit in a codebase, or integrate Tool UI payloads into assistant-ui or an existing chat/runtime stack.
ast-grep
Structural code search using Abstract Syntax Tree patterns for precise codebase queries.