Assistant UI
Overview
Use this skill to implement or debug assistant-ui integration end to end: CLI setup, runtime wiring, UI primitives, tool UI, and migration-safe upgrades. Load only the reference file needed for the current subtask to keep context focused.
Workflow
- Classify the task before coding. Determine whether the request is setup, runtime wiring, primitives, tools, cloud persistence, or migration. If the request includes explicit exclusion language (
without/no/not assistant-ui), stop and do not use this skill. - Select runtime and architecture first. Choose AI SDK, LangGraph, or external-store path before editing components.
- Apply setup commands with minimum blast radius. Prefer the smallest CLI operation (
addfor existing projects,createfor new projects). - Wire provider and thread lifecycle. Ensure
AssistantRuntimeProviderand runtime hook are configured before Thread/Composer work. - Implement tool UI using current APIs. Prefer
useAui + Tools({toolkit})for registration; usemakeAssistantToolUIfor UI-only bindings. - Validate and migrate safely. Run dry-run upgrade checks first, then codemods, then verification.
Runtime Decision Rules
- Choose AI SDK runtime when backend communication is a chat endpoint and no graph thread state is required.
- Choose LangGraph runtime when thread lifecycle (
initialize/create/load) and interrupts are required. - Choose external store runtime when app state is controlled outside assistant-ui.
- Add Assistant Cloud only when persistence, auth-linked thread continuity, or multi-device resume is required.
Load references/runtime-selection.md for the matrix and expected outputs.
Execution Protocol
- Read
references/setup-and-cli.mdfor command sequence and flags. - Read exactly one runtime reference.
- Read
references/langgraph-runtime.mdfor LangGraph. - Read
references/runtime-selection.mdfor AI SDK or external-store decisions.
- Read
references/tool-ui-patterns.mdonly if tools are in scope. - Read
references/cloud-persistence.mdonly if cloud is in scope. - Read
references/troubleshooting.mdonly when failures appear.
Output Contract
When implementing assistant-ui tasks, deliver these artifacts unless the user scope explicitly excludes them:
- Runtime provider wiring that matches the chosen runtime.
- Thread and composer integration that compiles with the chosen runtime.
- Tool registration and rendering behavior consistent with current APIs.
- Environment variable expectations for cloud flows.
- Upgrade path or migration notes if dependency upgrades are requested.
Guardrails
- Prefer
Tools({toolkit})over legacy registration helpers. - Use
makeAssistantToolUIonly for UI bindings to already-defined backend tools. - Keep LangGraph thread handling explicit:
initialize,create, andload. - Execute upgrade sequence in this order:
update --dry->upgrade->codemod-> test. - Avoid broad documentation dumps; load only relevant references.
- Do not activate this workflow for comparison-only requests that do not require assistant-ui implementation changes.
Reference Map
- Setup and CLI:
references/setup-and-cli.md - Runtime selection:
references/runtime-selection.md - LangGraph runtime wiring:
references/langgraph-runtime.md - Tool UI patterns:
references/tool-ui-patterns.md - Cloud persistence:
references/cloud-persistence.md - Debug and recovery:
references/troubleshooting.md