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

tool-ui-integrator skill

safe

This skill helps you quickly integrate Tool UI components into React apps by evaluating compatibility, scaffolding wiring, and troubleshooting.

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

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

Files (13)

SKILL.md

3.1 KB

---
name: tool-ui-integrator
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 Integrator

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 apps using shadcn registry entries and scaffolded runtime snippets. It automates compatibility checks, scaffolds frontend and backend wiring, and provides troubleshooting steps so integrations go from request to working UI quickly. Use it for single-component fixes or multi-component flows that connect tools into an assistant UI or an existing chat runtime.

How this skill works

The skill runs compatibility and doctor checks against the project to verify required metadata and registry entries, and can auto-fix missing @tool-ui entries. It discovers candidate components by intent, generates shadcn install commands, and scaffolds runtime wiring for assistant-backend, assistant-frontend, or manual modes. Finally it validates integrations with typechecks, real tool calls, and guided troubleshooting workflows.

When to use it

Add one or more Tool UI components to a React app
Choose components for a specific assistant or tool-driven use case
Verify project compatibility with Tool UI registries and aliases
Wire Tool UI payloads into assistant-ui or an existing chat/runtime stack
Scaffold runtime wiring for backend or frontend adapter code

Best practices

Run compatibility/doctor checks before installing to catch registry or alias issues
Install the smallest set of components that satisfies the use case, validate one first then scale
Keep payload schemas explicit and serializable to simplify runtime wiring
Prefer assistant-ui scaffolds if the project lacks a chat UI; skip if a mature runtime exists
Ensure user-driven callbacks call addResult(...) for interactive flows to persist results

Example use cases

Add a plan-execution component and wire its payloads into the assistant backend for task orchestration
Install a selection or option-list UI and connect it to an existing chat runtime for multi-choice interactions
Discover a bundle of components for a planning flow, scaffold frontend controls and backend handlers, and validate with real tool calls
Run the doctor command to auto-fix a missing @tool-ui registry and retry installation
Scaffold a manual stats-display component when only visual integration is needed without backend changes

FAQ

What minimum files and config are required?

components.json must exist, components.json.aliases.utils must point to a utilities path, and components.json.registries['@tool-ui'] should match the Tool UI registry URL pattern.

Can the tool auto-fix issues?

Yes — the doctor script can auto-fix missing @tool-ui registry entries and surface other actionable fixes via a --fix flag.

Which scaffold mode should I choose?

Use assistant-backend to generate backend handlers, assistant-frontend for UI wiring, and manual when you only need scaffold snippets or custom integration patterns.

How do I troubleshoot a broken integration?

Run typecheck/lint, trigger a real tool call, inspect logs for payload schema mismatches, and follow the troubleshooting patterns provided by the skill to correct wiring or component selection.