Assistant UI

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

1. 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.
2. Select runtime and architecture first. Choose AI SDK, LangGraph, or external-store path before editing components.
3. Apply setup commands with minimum blast radius. Prefer the smallest CLI operation (add for existing projects, create for new projects).
4. Wire provider and thread lifecycle. Ensure AssistantRuntimeProvider and runtime hook are configured before Thread/Composer work.
5. Implement tool UI using current APIs. Prefer useAui + Tools({ toolkit }) for registration; use makeAssistantToolUI for UI-only bindings.
6. 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

1. Read references/setup-and-cli.md for command sequence and flags.
2. Read exactly one runtime reference.

• Read references/langgraph-runtime.md for LangGraph.
• Read references/runtime-selection.md for AI SDK or external-store decisions.

3. Read references/tool-ui-patterns.md only if tools are in scope.
4. Read references/cloud-persistence.md only if cloud is in scope.
5. Read references/troubleshooting.md only 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 makeAssistantToolUI only for UI bindings to already-defined backend tools.
• Keep LangGraph thread handling explicit: initialize, create, and load.
• 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