home / skills / phrazzld / claude-config / agentic-ui-contract

agentic-ui-contract skill

safe

This skill enables agentic product flows by enforcing a contract where model decides WHAT, tools decide HOW, and UI renders blocks.

npx playbooks add skill phrazzld/claude-config --skill agentic-ui-contract

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

Files (1)

SKILL.md

2.1 KB

---
name: agentic-ui-contract
description: |
  Design and implement agentic product flows using the contract:
  model decides what to do, tools decide how it is done, UI schema decides
  how it is rendered. Use for chat-first apps, tool-calling agents,
  generative UI systems, and planner/tool architecture decisions.
  Keywords: agentic UX, tool calling, planner, generative UI, function tools.
effort: high
---

# Agentic UI Contract

Use this when building or refactoring toward agentic product behavior.

## Core Contract

1. Model decides WHAT to do.
2. Tools decide HOW it is done.
3. UI schema decides HOW it is rendered.

This gives open-ended behavior without fragile freeform execution.

## Architecture Shape

- Planner layer (LLM): intent interpretation + tool selection + sequencing.
- Tool layer (deterministic): typed side effects and data reads.
- UI contract layer (typed blocks): constrained rendering catalog.
- Control layer: auth, guardrails, tracing, evals, fallback.

## Rules

- Never let model write directly to persistence.
- Never trust model-generated metrics; compute metrics deterministically.
- Keep tool interfaces deep (few, meaningful tools), avoid tiny tool explosions.
- Keep UI blocks strict and versionable.
- Treat planner failure as recoverable; fallback to deterministic behavior.

## Implementation Workflow

1. Define typed block schema first.
2. Define deep tool surface second.
3. Implement server planner tool loop third.
4. Keep client thin: send messages, render blocks, apply client actions.
5. Add traces and eval fixtures before widening scope.

## Readiness Checklist

- [ ] Tool args validated with schema.
- [ ] Tool outputs deterministic and structured.
- [ ] Planner cannot bypass tools for data claims.
- [ ] UI renders only whitelisted block types.
- [ ] Planner + tool traces available per turn.
- [ ] Deterministic fallback path exists.

## Anti-Patterns

- Regex parser as primary intelligence layer.
- Model directly composing arbitrary UI markup/components.
- Over-fragmented tools that mirror internal implementation.
- Allowing model narration to replace data tool calls.
- No eval harness for prompt/tool regressions.

Overview

This skill codifies an agentic UI contract for building chat-first, tool-calling, and planner-driven products. It separates responsibility so the model decides intent, tools perform deterministic work, and a typed UI schema controls rendering. The contract reduces brittle freeform behavior and makes agent actions auditable and versionable.

How this skill works

You define a typed UI block schema, expose a curated set of deep tools with validated arguments, and implement a server-side planner loop that maps model intent to tool calls and UI blocks. The client remains thin: it renders whitelisted blocks, forwards user interactions, and applies client-side actions. Tracing, deterministic fallbacks, and strict tool outputs ensure reliability and evaluability.

When to use it

Building chat-first apps that must call backend tools or APIs reliably.
Designing planner + tool architectures where intent and execution are separated.
Creating generative UIs where model proposes structure but UI renders deterministically.
Refactoring systems where models currently write directly to persistence or UI markup.
Implementing audit, tracing, and deterministic fallbacks for agent behavior.

Best practices

Define the typed UI block schema before tool or planner implementation.
Keep tools deep and meaningful; avoid many tiny, implementation-leaking tools.
Validate all tool arguments and enforce structured, deterministic outputs.
Disallow the model from writing directly to persistence or composing arbitrary markup.
Version UI block types and maintain a deterministic fallback path for planner failures.

Example use cases

A planner that sequences API calls, returns structured results, and the UI renders results as cards and forms.
A tool-calling assistant that performs transactions through validated tool interfaces while the model drives intent and explanations.
A generative dashboard where the model suggests layouts as typed blocks and the client renders only whitelisted components.
A ticketing workflow where the planner selects steps, tools execute side effects, and traces are recorded for audits.
A conversational product designer that proposes UI schemas; developers map those schemas to concrete components.

FAQ

What prevents the model from fabricating data claims?

Require all data used for decisions to come from deterministic tool outputs and prevent planner text from bypassing tool results.

How do I handle planner errors or hallucinations?

Treat planner failures as recoverable: provide deterministic fallback behaviors, log traces, and surface evaluation fixtures to detect regressions.