Skill installation

npx skills add https://github.com/assistant-ui/tool-ui --skill tool-ui

What's included

This package gives coding agents everything they need to integrate Tool UI components:

• SKILL.md — the five-step workflow (see below)
• Reference docs — component catalog, recipes, integration patterns, troubleshooting
• CLI scripts — compatibility checks, search, scaffolding
• Test suites — regression coverage for the scripts

SKILL.md — the workflow

.agents/skills/tool-ui/SKILL.md is the entry point. Follow these five steps:

1. Compatibility check — verify prerequisites (shadcn/ui, Tailwind, Radix)
2. Discover — search and browse available components
3. Install — pull components from the registry
4. Scaffold — generate adapter files and runtime wiring code
5. Validate — confirm the integration works

Each step links to the relevant script or reference doc.

Reference docs

All reference material lives in .agents/skills/tool-ui/references/.

Discover

components-catalog.md — Browse components by category. Each entry includes a description and guidelines for picking the right one for your use case.

components-data.json — Machine-readable metadata that the CLI scripts use for search and install operations.

Install

recipes.md — Pre-built bundles for common patterns (planning flow, research output, commerce flow). Each recipe has a one-line install command that pulls the entire bundle.

Scaffold

integration-patterns.md — Five wiring patterns with full code examples:

• Backend display — render tool results as read-only UI
• Backend + local actions — add inline actions alongside backend data
• Frontend decision — collect user input before proceeding
• Action-centric — surface standalone actions without surrounding content
• Manual — wire components directly without the runtime framework

Validate

troubleshooting.md — Symptom → cause → fix matrix for common install and runtime issues.

CLI scripts

All scripts live in .agents/skills/tool-ui/scripts/.

tool_ui_compat.py

Checks components.json compatibility, auto-fixes the @tool-ui registry entry, and runs deeper doctor checks — shared folder presence, import resolution, and package dependencies.

tool_ui_components.py

Lists, searches, and generates install commands for components. Also handles bundle recipes from recipes.md. Reads from components-data.json for fast lookups.

tool_ui_scaffold.py

Generates ready-to-paste runtime wiring code in three modes: assistant-backend, assistant-frontend, and manual. Output adapts to the project's framework and integration pattern.

Test suites

Script tests in .agents/skills/tool-ui/tests/ provide regression coverage for the CLI scripts. They validate SKILL.md references, script syntax, and data integrity.