playbooks

home / skills / petekp / claude-code-setup / tool-ui

tool-ui skill

/skills/tool-ui

This skill helps you integrate Tool UI components into React apps quickly by discovering, installing, scaffolding, and validating runtime wiring.

npx playbooks add skill petekp/claude-code-setup --skill tool-ui

Review the files below or copy the command above to add this skill to your agents.

Files (13)
SKILL.md
3.0 KB
---
name: tool-ui
description: Find, install, configure, and integrate Tool UI components in React apps using shadcn registry entries, compatibility checks, scaffolded runtime wiring, and troubleshooting workflows. Use when developers ask to add one or more Tool UI components, choose components for a use case, verify compatibility, or wire Tool UI payloads into assistant-ui or an existing chat/runtime stack.
---

# Tool UI

Use this skill to move from request to working Tool UI integration quickly.

Prefer assistant-ui when the project has no existing chat UI/runtime. Treat assistant-ui as optional when the app already has a working runtime.

## Workflow

1. Run compatibility and doctor checks.
2. Find candidate components or bundles.
3. Install selected components.
4. Generate scaffolds and integrate runtime wiring.
5. Validate behavior and troubleshoot failures.

## Step 1: Compatibility and Doctor

```bash
python scripts/tool_ui_compat.py --project <repo-root>
python scripts/tool_ui_compat.py --project <repo-root> --doctor
```

Auto-fix missing `@tool-ui` registry entry:

```bash
python scripts/tool_ui_compat.py --project <repo-root> --fix
```

Minimum requirements:

- `components.json` exists.
- `components.json.aliases.utils` exists (typically `@/lib/utils`).
- `components.json.registries["@tool-ui"]` equals `https://tool-ui.com/r/{name}.json`.

## Step 2: Discover Components

Use intent-first discovery:

```bash
python scripts/tool_ui_components.py list
python scripts/tool_ui_components.py find "<use case keywords>"
python scripts/tool_ui_components.py bundle
python scripts/tool_ui_components.py bundle planning-flow
```

References:

- `references/components-catalog.md`
- `references/recipes.md`

## Step 3: Install Components

Generate install command:

```bash
python scripts/tool_ui_components.py install <component-id> [component-id...]
```

Default install pattern:

```bash
npx shadcn@latest add https://tool-ui.com/r/<component-id>.json
```

## Step 4: Scaffold and Integrate

Generate wiring snippet:

```bash
python scripts/tool_ui_scaffold.py --mode assistant-backend --component plan
python scripts/tool_ui_scaffold.py --mode assistant-frontend --component option-list
python scripts/tool_ui_scaffold.py --mode manual --component stats-display
```

Use integration patterns for final adaptation:

- `references/integration-patterns.md`

## Step 5: Validate and Troubleshoot

After integration:

1. Run typecheck/lint.
2. Trigger a real tool call.
3. Confirm UI renders and interactions complete expected flow.

If broken, use:

- `references/troubleshooting.md`

## Operational Rules

- Install the smallest set of components that solves the request.
- Validate one component first, then scale to multiple components.
- Keep payload schemas serializable and explicit.
- For interactive flows, ensure `addResult(...)` is called from user action callbacks.

## Maintainer Notes

Keep component metadata synchronized with Tool UI source:

```bash
python scripts/sync_components.py
```

Run script tests:

```bash
python -m unittest discover -s tests -p "test_*.py"
```

Overview

This skill helps developers find, install, configure, and wire Tool UI components into React applications using the shadcn registry and supplied scripts. It speeds integration from discovery to a working runtime, includes compatibility checks, scaffolding for frontend and backend wiring, and troubleshooting guidance. Use it to add single components or full component bundles and verify runtime compatibility with assistant-ui or an existing chat stack.

How this skill works

The skill runs automated compatibility and doctor checks against the project, discovers candidate components by intent keywords or bundles, and generates installation commands based on shadcn registry entries. It scaffolds runtime wiring snippets for frontend and backend modes, provides patterns for manual adaptation, and supplies validation and troubleshooting steps to confirm UI behavior and tool-call flows.

When to use it

  • Adding one or more Tool UI components to a React app
  • Choosing components to match a specific user flow or intent
  • Verifying registry and project compatibility before install
  • Scaffolding runtime wiring for assistant-ui or a custom chat/runtime stack
  • Troubleshooting rendering, type, or runtime issues after integration

Best practices

  • Run compatibility and doctor checks before discovering components to catch missing registry entries or alias issues
  • Install the minimal set of components that satisfy the request and validate each component incrementally
  • Prefer assistant-ui when no chat runtime exists; treat it as optional if a runtime is already in place
  • Keep payload schemas explicit and serializable; avoid sending complex non-serializable objects to UI components
  • Ensure interactive callbacks call addResult(...) from a user action to complete tool flows

Example use cases

  • Add a planning UI: find a planning-flow bundle, install, scaffold assistant-backend wiring, and validate a real tool call
  • Integrate an option list into an existing chat runtime: run compatibility checks, install option-list, scaffold frontend snippet, and wire payload handlers
  • Replace a simple stats widget with a Tool UI stats-display: install component, scaffold manual mode, adapt payload schema, and run typecheck/lint
  • Create a new assistant-ui chat: install a bundle of chat components, scaffold assistant-frontend and assistant-backend wiring, then run validation and troubleshooting

FAQ

What minimum files or settings are required in the project?

components.json must exist, components.json.aliases.utils must be set (commonly @/lib/utils), and components.json.registries['@tool-ui'] must point to https://tool-ui.com/r/{name}.json.

How do I auto-fix missing registry entries?

Run the compatibility script with --fix: python scripts/tool_ui_compat.py --project <repo-root> --fix to insert the @tool-ui registry entry automatically.

When should I prefer assistant-ui over manual integration?

Prefer assistant-ui when the project has no existing chat UI or runtime. If a stable runtime already exists, use the provided manual/assistant-frontend scaffolds and integration patterns instead.