The Open Standard for Generative UI
Add Agent Skill for OpenUI (#343)
ABd982a4154451
diff --git a/README.md b/README.mdindex 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.+## LicenseThis 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.mdxindex 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 setupThe fastest way to get started — authenticates via OAuth, generates an API key, and installs the appropriate skill:@@ -23,10 +23,42 @@ npx ctx7 setupUse `--cursor`, `--claude`, or `--opencode` to target a specific agent.-## Manual setup+### Manual setupFor 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 docsFor 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.mdxindex 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.jsonindex 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.mdxindex 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 Rules1. **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 ArgumentsOptional 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 Examplediff --git a/docs/content/docs/openui-lang/troubleshooting.mdx b/docs/content/docs/openui-lang/troubleshooting.mdxnew file mode 100644index 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 countdiff --git a/skills/openui/SKILL.md b/skills/openui/SKILL.mdnew file mode 100644index 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 />`.