🎨 A2UI Skill — Agent-to-UI Protocol Reference

A comprehensive AI coding assistant skill for building agents that generate rich, interactive UIs via the A2UI protocol.

---

What is this?

This is a skill (structured knowledge pack) for AI coding assistants that teaches them the A2UI protocol — enabling them to help you build agents that generate rich, interactive UIs as safe, declarative JSON.

A2UI (Agent-to-UI) is an open-source protocol by Google that lets AI agents describe UI intent as JSON messages. Client renderers (React, Angular, Lit, Flutter) convert these messages into native components. No code execution — just safe, declarative data.

What the skill covers

Reference File	Contents
protocol.md	Protocol architecture, message types, v0.8→v0.9 migration
components.md	Full Basic Catalog — all 16 components with v0.9 syntax
data-binding.md	Data model, JSON Pointer paths, reactive bindings, templates
actions.md	Events, functions, action wiring, data model sync, orchestration
adk-integration.md	Python ADK integration — schema manager, parsing, streaming, validation
client-setup.md	React, Lit, Angular, Flutter renderer setup
catalogs.md	Custom catalogs, negotiation, versioning, build tools
examples.md	Complete working examples — restaurant list, booking form, confirmation

Total: ~2,000 lines of structured reference material across 9 files.

---

Installation

Gemini CLI

git clone https://github.com/oktony/a2ui-skill.git ~/.gemini/skills/a2ui-guide

Or if you want to place it manually:

# Download and copy
git clone https://github.com/oktony/a2ui-skill.git /tmp/a2ui-skill
cp -R /tmp/a2ui-skill/SKILL.md /tmp/a2ui-skill/references ~/.gemini/skills/a2ui-guide/
rm -rf /tmp/a2ui-skill

Cline (VS Code)

git clone https://github.com/oktony/a2ui-skill.git ~/.agents/skills/a2ui-guide

One-Command Install (Auto-Detect)

curl -sSL https://raw.githubusercontent.com/oktony/a2ui-skill/main/install.sh | bash

Or clone and run locally:

git clone https://github.com/oktony/a2ui-skill.git
cd a2ui-skill
./install.sh

---

Usage

Once installed, the skill is automatically available to your AI coding assistant.

In Gemini CLI

The skill activates when you work on A2UI-related tasks. You can also explicitly reference it:

@a2ui-guide Help me build an agent that generates a restaurant booking form

In Cline

Use the skill command:

/a2ui-guide

Or it activates automatically when your task matches the skill description (building agents with A2UI).

---

Quick Example

Here's what A2UI looks like — a complete UI described in JSON:

[
  {
    "version": "v0.9",
    "createSurface": {
      "surfaceId": "hello",
      "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
    }
  },
  {
    "version": "v0.9",
    "updateComponents": {
      "surfaceId": "hello",
      "components": [
        { "id": "root", "component": "Column", "children": ["greeting", "action-btn"] },
        { "id": "greeting", "component": "Text", "text": "Hello, World!", "variant": "h1" },
        { "id": "action-btn", "component": "Button", "child": "btn-label", "variant": "primary",
          "action": { "event": { "name": "greet" } } },
        { "id": "btn-label", "component": "Text", "text": "Say Hello" }
      ]
    }
  }
]

The agent generates this JSON → the transport delivers it → the renderer draws native UI components. Safe, declarative, framework-agnostic.

---

Supported AI Tools

Tool	Skill Location	Status
Gemini CLI	~/.gemini/skills/a2ui-guide/	✅ Tested
Cline (VS Code)	~/.agents/skills/a2ui-guide/	✅ Tested

The skill format (SKILL.md + references/) is shared between Gemini CLI and Cline. The same files work in both tools.

---

A2UI Version Coverage

Version	Status	Coverage
v0.9	Primary	Full — all components, messages, patterns
v0.8	Stable	Migration reference, key differences
v0.10	Draft	Awareness, pointer to spec

---

File Structure

a2ui-skill/
├── SKILL.md                          # Skill entry point (metadata + quick start)
├── references/
│   ├── protocol.md                   # Protocol overview, message types, versions
│   ├── components.md                 # Component catalog cheatsheet
│   ├── data-binding.md               # Data model, paths, reactive bindings
│   ├── actions.md                    # Events, functions, data sync
│   ├── adk-integration.md            # Python ADK integration patterns
│   ├── client-setup.md               # Renderer setup (React/Lit/Angular/Flutter)
│   ├── catalogs.md                   # Custom catalogs, negotiation, versioning
│   └── examples.md                   # Complete working examples
├── install.sh                        # One-command installer
├── LICENSE                           # Apache 2.0
└── README.md                         # This file

---

Updating

To update to the latest version:

# Gemini CLI
cd ~/.gemini/skills/a2ui-guide && git pull

# Cline
cd ~/.agents/skills/a2ui-guide && git pull

---

Uninstalling

# Gemini CLI
rm -rf ~/.gemini/skills/a2ui-guide

# Cline
rm -rf ~/.agents/skills/a2ui-guide

---

Contributing

Contributions welcome! If you find errors, want to add examples, or improve coverage:

1. Fork this repo
2. Make your changes
3. Submit a pull request

Guidelines

• Keep reference files focused and scannable
• Use v0.9 syntax as primary, note v0.8 differences where relevant
• Include working JSON examples — they're the most useful part
• Test with both Gemini CLI and Cline if possible

---

Related Resources

• A2UI Repository — Official A2UI protocol and renderers
• A2UI Documentation — Full protocol documentation
• Google ADK — Agent Development Kit for Python
• Gemini CLI — Google's CLI coding assistant
• A2A Protocol — Agent-to-Agent communication protocol

---

License

Apache License 2.0 — Same as A2UI itself.

---

Built with ❤️ for the A2UI community