Skip to content

The Open Standard for Generative UI

Add Agent Skill for OpenUI (#343)

ABd982a4154451
diff --git a/README.md b/README.md
index f16e5b052..d67cebb5c 100644
--- a/README.md
+++ b/README.md
@@ -137,6 +137,8 @@ openui/
│ ├── react-headless/ # Headless chat state & streaming adapters
│ ├── react-ui/ # Prebuilt chat layouts & component libraries
│ └── openui-cli/ # CLI for scaffolding & prompt generation
+├── skills/
+│ └── openui/ # Claude Code skill for AI-assisted development
├── examples/
│ └── openui-chat/ # Full working example app (Next.js)
├── docs/ # Documentation site (openui.com)
@@ -159,6 +161,22 @@ Good places to start:
Contributions are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for contribution guidelines and ways to get involved.
+## Agent Skill
+
+OpenUI ships an [Agent Skill](https://agentskills.io) so AI coding assistants (Claude Code, Codex, Cursor, Copilot, etc.) can help you scaffold, build, and debug Generative UI apps using OpenUI Lang.
+
+### Install
+
+```bash
+# With the skills CLI (works across all agents)
+npx skills add thesysdev/openui --skill openui
+
+# Manual — copy into your project
+cp -r skills/openui .claude/skills/openui
+```
+
+The skill covers component library design, OpenUI Lang syntax, system prompt generation, the Renderer, SDK packages, and debugging malformed LLM output.
+
## License
This project is available under the terms described in [`LICENSE`](./LICENSE).
diff --git a/docs/content/docs/mcp/index.mdx b/docs/content/docs/mcp/index.mdx
index 7de8eb9ab..d923fb5c9 100644
--- a/docs/content/docs/mcp/index.mdx
+++ b/docs/content/docs/mcp/index.mdx
@@ -1,6 +1,6 @@
---
-title: Documentation MCP Server
-description: Connect OpenUI documentation to your AI coding tools via MCP.
+title: AI-Assisted Development
+description: Connect OpenUI documentation to your AI coding tools via MCP, agent skills, or LLM-friendly doc formats.
---
## MCP Server
@@ -13,7 +13,7 @@ Add `use context7` to any prompt, or reference the library explicitly:
use library /thesysdev/openui
```
-## Quick setup
+### Quick setup
The fastest way to get started — authenticates via OAuth, generates an API key, and installs the appropriate skill:
@@ -23,10 +23,42 @@ npx ctx7 setup
Use `--cursor`, `--claude`, or `--opencode` to target a specific agent.
-## Manual setup
+### Manual setup
For manual installation instructions for 30+ clients (Cursor, VS Code, Claude Desktop, Windsurf, ChatGPT, Lovable, Replit, JetBrains, and more), see the [Context7 MCP Clients](https://context7.com/docs/resources/all-clients) page.
+## Agent Skill
+
+OpenUI ships an [Agent Skill](https://agentskills.io) that teaches AI coding assistants how to build Generative UI apps with OpenUI Lang. Once installed, your AI assistant can scaffold projects, define components, generate system prompts, wire up the `Renderer`, and debug malformed LLM output.
+
+Works with Claude Code, Cursor, GitHub Copilot, Codex, and any agent that supports the [agentskills.io](https://agentskills.io) standard.
+
+### Install via the skills CLI (recommended)
+
+```bash
+npx skills add thesysdev/openui --skill openui
+```
+
+### Manual copy
+
+If you already have the OpenUI repo cloned:
+
+```bash
+mkdir -p .claude/skills
+cp -r /path/to/openui/skills/openui .claude/skills/openui
+```
+
+### What the skill covers
+
+| Area | Details |
+| :----------------- | :---------------------------------------------------------------------------- |
+| Component design | `defineComponent`, `createLibrary`, `.ref` composition, schema ordering |
+| OpenUI Lang syntax | Expression types, positional args, forward references, streaming rules |
+| System prompts | `library.prompt()`, `preamble`, `additionalRules`, `examples`, CLI generation |
+| Rendering | `<Renderer />`, progressive rendering, `onAction`, `onParseResult` |
+| SDK packages | `react-lang`, `react-headless`, `react-ui` — when to use each |
+| Debugging | Diagnosing malformed output, validation errors, unresolved forward refs |
+
## LLM-friendly docs
For tools that support `llms.txt`, or if you want to load docs directly into context:
diff --git a/docs/content/docs/openui-lang/defining-components.mdx b/docs/content/docs/openui-lang/defining-components.mdx
index f0e1075cb..26467e382 100644
--- a/docs/content/docs/openui-lang/defining-components.mdx
+++ b/docs/content/docs/openui-lang/defining-components.mdx
@@ -184,6 +184,38 @@ const prompt = library.prompt(options);
See [System Prompts](/docs/openui-lang/system-prompts) for full details on prompt generation.
+## Best practices for LLM generation
+
+Since LLMs are the ones writing OpenUI Lang, component design choices directly affect generation quality.
+
+### Keep schemas flat
+
+Deeply nested object props burn tokens and increase error rates. Prefer multiple simple components over one deeply nested one.
+
+### Order Zod keys deliberately
+
+Required props first, optional props last. The most important or distinctive prop should be position 0 — the LLM sees it first during generation.
+
+### Use descriptive component names
+
+The LLM picks components by name. `PricingTable` is clearer than `Table3`. The `description` field reinforces this.
+
+### Limit library size
+
+Every component adds to the system prompt. Include only components the LLM actually needs for the use case. Fewer components means less confusion and better output.
+
+### Use `.ref` for composition, not deep nesting
+
+`z.array(ChildComponent.ref)` is the idiomatic way to compose. The LLM generates each child as a separate line, which streams and validates independently.
+
+### Provide examples in `PromptOptions`
+
+One or two concrete examples dramatically improve output quality, especially for complex or unusual component shapes. See [System Prompts](/docs/openui-lang/system-prompts) for details.
+
+### Use `componentGroups` with notes
+
+Group related components and add notes like "Use BarChart for comparisons, LineChart for trends" to guide the LLM's choices. See [Grouping components](#grouping-components-in-prompt-output) above.
+
## Next Steps
<Cards>
diff --git a/docs/content/docs/openui-lang/meta.json b/docs/content/docs/openui-lang/meta.json
index 648c604c0..6f7dd920d 100644
--- a/docs/content/docs/openui-lang/meta.json
+++ b/docs/content/docs/openui-lang/meta.json
@@ -10,6 +10,7 @@
"system-prompts",
"renderer",
"interactivity",
+ "troubleshooting",
"---Advanced---",
"specification",
"benchmarks",
diff --git a/docs/content/docs/openui-lang/specification.mdx b/docs/content/docs/openui-lang/specification.mdx
index f6661b065..e24a7bd74 100644
--- a/docs/content/docs/openui-lang/specification.mdx
+++ b/docs/content/docs/openui-lang/specification.mdx
@@ -23,7 +23,7 @@ s2 = Series("Product B", [5, 15, 25])
## Core Rules
1. **One statement per line:** `identifier = Expression`
-2. **Root Entry Point:** The first statement **must** assign to the identifier `root` (or call the Root component).
+2. **Root Entry Point:** The first statement **must** assign to the identifier `root` (or call the Root component). If missing, nothing renders.
3. **Top-Down Generation:** Statements are generally written top-down (Layout -> Components -> Data) to maximize perceived performance during streaming.
4. **Positional Arguments:** Arguments are mapped to component props by position, defined by the order of keys in your Zod schema.
@@ -78,6 +78,12 @@ h1 = Header("Dashboard", "Overview")
}
```
+### Critical implications for component design
+
+- **Key order in z.object is the API contract.** Changing key order breaks all existing LLM outputs.
+- **Required props must come before optional props** in the schema, since trailing optional args can be omitted.
+- **The LLM learns positions from the auto-generated system prompt.** If the prompt and schema disagree (e.g., after a schema change without regenerating the prompt), output will be garbled.
+
## Optional Arguments
Optional arguments (trailing) can be omitted.
@@ -103,6 +109,7 @@ table = Table(rows) // ...but defined here.
1. **Step 1:** The renderer parses `root`. It sees `table` is undefined. It renders a **Skeleton/Placeholder** for the table.
2. **Step 2:** The `table` definition arrives. The renderer updates the React tree, replacing the skeleton with the actual `Table` component.
+3. **Step 3:** `rows` arrives → Table fills in with data.
## Complete Syntax Example
diff --git a/docs/content/docs/openui-lang/troubleshooting.mdx b/docs/content/docs/openui-lang/troubleshooting.mdx
new file mode 100644
index 000000000..5144e81ed
--- /dev/null
+++ b/docs/content/docs/openui-lang/troubleshooting.mdx
@@ -0,0 +1,95 @@
+---
+title: Troubleshooting
+description: Common issues and fixes when working with OpenUI Lang and the Renderer.
+---
+
+## LLM Output Issues
+
+### Why is nothing rendering?
+
+The first statement must assign to `root`. Without it, nothing renders.
+
+```text
+// Wrong — no root
+header = Header("Title")
+body = TextContent("Content")
+
+// Correct
+root = Stack([header, body])
+header = Header("Title")
+body = TextContent("Content")
+```
+
+### Why are extra arguments being dropped?
+
+Providing more arguments than the schema defines causes the extra arguments to be dropped or the statement to fail validation.
+
+```text
+// Schema: z.object({ title: z.string(), subtitle: z.string() })
+
+// Wrong — 3 args for a 2-prop schema
+h1 = Header("Title", "Sub", "extra")
+
+// Correct
+h1 = Header("Title", "Sub")
+```
+
+### Why is a component not appearing?
+
+The LLM may invent component names that are not in the library. The parser drops any statement that references an unknown component.
+
+```text
+// Wrong — "Paragraph" is not registered
+text = Paragraph("Hello world")
+
+// Correct — use the registered name
+text = TextContent("Hello world")
+```
+
+### Can I nest children inline or do I need references?
+
+Both are valid — inline children or references work.
+
+```text
+// Inline
+root = Stack([Header("Title"), TextContent("Body")])
+
+// References
+root = Stack([h, t])
+h = Header("Title")
+t = TextContent("Body")
+```
+
+## Renderer Issues
+
+### How do I inspect what went wrong?
+
+Pass an `onParseResult` callback to `<Renderer />`. Inspect `meta.errors` for schema mismatches and `meta.unresolved` for identifiers that were referenced but never defined.
+
+```tsx
+<Renderer
+ library={library}
+ response={content}
+ isStreaming={isStreaming}
+ onParseResult={(result) => {
+ if (result) {
+ console.log("Validation errors:", result.meta.errors);
+ console.log("Unresolved refs:", result.meta.unresolved);
+ }
+ }}
+/>
+```
+
+### Why are props appearing in the wrong position?
+
+The key order in your `z.object({...})` is the contract for positional arguments. If you changed the key order without regenerating the system prompt, the LLM's arguments will map incorrectly.
+
+Call `library.toJSONSchema()` to see exactly what the parser expects, and compare it against what the LLM is generating.
+
+### Why are parts of the UI missing?
+
+The parser drops invalid portions and renders everything else. If parts of the UI are missing, log the raw streamed text before parsing and look for:
+
+- Missing `root` assignment
+- Typos in component names
+- Wrong argument count
diff --git a/skills/openui/SKILL.md b/skills/openui/SKILL.md
new file mode 100644
index 000000000..560a1d99d
--- /dev/null
+++ b/skills/openui/SKILL.md
@@ -0,0 +1,94 @@
+---
+name: openui
+description: "Build generative UI apps with OpenUI and OpenUI Lang — the token-efficient open standard for LLM-generated interfaces. Use when mentioning OpenUI, @openuidev, generative UI, streaming UI from LLMs, component libraries for AI, or replacing json-render/A2UI. Covers scaffolding, defineComponent, system prompts, the Renderer, and debugging OpenUI Lang output."
+---
+
+# OpenUI — The Open Standard for Generative UI
+
+OpenUI is a full-stack Generative UI framework by Thesys. At its center is **OpenUI Lang**: a compact, line-oriented language designed for LLMs to generate user interfaces, up to 67% more token-efficient than JSON-based alternatives.
+
+Instead of treating LLM output as only text/markdown, OpenUI lets you define a component library, auto-generate a system prompt from it, and render structured UI progressively as the model streams.
+
+## Core Architecture
+
+OpenUI has four building blocks that form a pipeline:
+
+1. **Library** — Components defined with Zod schemas + React renderers via `defineComponent`. This is the contract between app and AI: it constrains what the LLM can generate.
+2. **Prompt Generator** — `library.prompt()` converts the library into a system prompt with syntax rules, component signatures, and streaming guidelines.
+3. **Parser** — Parses OpenUI Lang line-by-line (streaming-compatible) into a typed element tree. Validates against the library's JSON Schema.
+4. **Renderer** — The `<Renderer />` React component maps parsed elements to your React components, rendering progressively as the stream arrives.
+
+```
+Component Library → System Prompt → LLM → OpenUI Lang Stream → Parser → Renderer → Live UI
+```
+
+## OpenUI Lang Overview
+
+OpenUI Lang is a compact, declarative, line-oriented DSL. The LLM generates this instead of JSON or markdown.
+
+### Syntax Rules (Critical)
+
+1. **One statement per line:** `identifier = Expression`
+2. **Root entry point:** The first statement MUST assign to the identifier `root`.
+3. **Top-down generation:** Write Layout → Components → Data for best streaming performance.
+4. **Positional arguments:** Arguments map to component props by position, determined by key order in the Zod schema.
+5. **Forward references (hoisting):** An identifier can be referenced before it's defined — the renderer shows a skeleton/placeholder until the definition arrives.
+
+Example:
+
+```
+root = Stack([header, stats])
+header = TextContent("Q4 Dashboard", "large-heavy")
+stats = Grid([s1, s2])
+s1 = StatCard("Revenue", "$1.2M", "up")
+s2 = StatCard("Users", "450k", "flat")
+```
+
+## Documentation
+
+For comprehensive reference, fetch the full documentation:
+
+```
+https://www.openui.com/llms-full.txt
+```
+
+For a topic index (page titles and descriptions only):
+
+```
+https://www.openui.com/llms.txt
+```
+
+When you need detail on a specific topic, fetch the relevant page:
+
+| Topic | URL |
+| -------------------------- | ----------------------------------------------------------- |
+| Quickstart & scaffolding | https://www.openui.com/docs/openui-lang/quickstart |
+| Defining components | https://www.openui.com/docs/openui-lang/defining-components |
+| System prompts | https://www.openui.com/docs/openui-lang/system-prompts |
+| Renderer | https://www.openui.com/docs/openui-lang/renderer |
+| Language specification | https://www.openui.com/docs/openui-lang/specification |
+| Interactivity | https://www.openui.com/docs/openui-lang/interactivity |
+| Built-in component library | https://www.openui.com/docs/openui-lang/standard-library |
+
+## SDK Packages
+
+| Package | Purpose | When to use |
+| --------------------------- | ----------------------------------------------------------------------- | ------------------------- |
+| `@openuidev/react-lang` | Core: defineComponent, createLibrary, Renderer, parser | Every OpenUI project |
+| `@openuidev/react-headless` | Chat state: ChatProvider, hooks, streaming adapters (OpenAI, AG-UI) | Custom chat UI |
+| `@openuidev/react-ui` | Prebuilt layouts (Copilot, FullScreen, BottomTray) + built-in libraries | Fast path to working chat |
+
+## Scaffolding
+
+```bash
+npx @openuidev/cli@latest create --name my-genui-app
+cd my-genui-app
+echo "OPENAI_API_KEY=sk-your-key-here" > .env
+npm run dev
+```
+
+## Framework Integration
+
+OpenUI works with any LLM framework. The scaffolded app uses Next.js with the OpenAI SDK. Integration patterns exist for: Vercel AI SDK, LangChain, CrewAI, OpenAI Agents SDK, Anthropic Agents SDK, Google ADK, and any framework that produces a text stream.
+
+The core integration point is always the same: send the system prompt (from `library.prompt()`) to your LLM, then feed the streamed text into `<Renderer />`.