Skip to content
Forms, switch product

Getting started with AI

GolemUI shipped after the training cutoff of every current model — so your AI assistant has never seen it. On its own, it will guess at the API, and guesses break the runtime. Grounding fixes that: you give the assistant the real, current GolemUI API so it generates correct forms instead of inventing them. This page takes you from nothing to a form your AI built.

Why your AI needs grounding

Section titled “Why your AI needs grounding”

Without grounding, an assistant has no reliable knowledge of GolemUI: it reaches for widget kinds and prop names that look plausible but don’t exist, and one wrong property breaks the form. There are two ways to close that gap, and they solve different halves of the problem:

  • The agent skill is the knowledge layer — the API reference plus the rules for using it, installed into your agent. One command, no server, works in the most tools.
  • The MCP server is the verification layer — deterministic tools that type-check the generated code, validate a definition against the shipped schemas, and generate forms from a JSON Schema or OpenAPI spec. No LLM calls happen inside it.

Both are version-locked to a GolemUI release and built from the same compile-verified source, so they never disagree. Use both if you can: the skill tells the assistant what to write, the MCP proves it compiles. Either way the assistant works in a tight look-up → write → check loop until the form is clean.

Step 1 — Set up grounding

Section titled “Step 1 — Set up grounding”

Pick a setup. Whichever you choose, it has to be in place before you prompt — skills and MCP tools both load when the assistant starts.

The strongest setup: the assistant writes from the skill and verifies with the MCP in the same turn.

  1. Create an empty folder for the app and open it:

    Terminal window
    mkdir my-form-app && cd my-form-app

  2. Install the skill and add the MCP:

    Terminal window
    npx skills add golemui/golemui
    claude mcp add golemui -- npx -y @golemui/gui-mcp

    (The second line is Claude Code’s syntax — for Cursor, Windsurf, or VS Code, add the server to your editor’s MCP config instead, per Setup.)

  3. Start your assistant in that folder — or restart it if it was already running, so both the skill and the MCP tools load.

  4. (Optional) Confirm: npx skills list shows golemui, and claude mcp list shows golemui ✓ Connected.

Step 2 — Describe your form

Section titled “Step 2 — Describe your form”

You don’t write GolemUI by hand — you describe the form in plain English and let the grounded assistant build it.

First, a choice it can’t make for you. A GolemUI form can be authored two ways:

  • Writing a normal app? Ask for the typed {gui.} builder. TypeScript, autocompleted, type-checked, smaller, and easy to review — the right default when the form lives in your codebase. It’s what the prompt below uses.
  • Need the form as portable data — stored in a database or CMS, generated at runtime, sent over the wire? Ask for a JSON form definition instead. (Already have a JSON Schema or OpenAPI spec? The MCP maps it straight to a form — see Generating from a schema.)

Same engine, same widgets — only the surface differs, and both are validated against the same schemas. If you have the skill installed and don’t say which you want, the assistant will stop and ask rather than guess; with the MCP alone, say it explicitly in your prompt.

Here’s a ready prompt — pick your framework and copy it into your AI:

✦ Prompt 
Build a simple Contact form.

The form has the following fields (use the natural input type for each):
1. Full name — text, required.
2. Email — text, required; must be a valid email address.
3. Subject — a dropdown: Question / Feedback / Bug report, required.
4. Message — a multi-line textarea, required.

Give the form a clear title, validate every field, and keep the submit button disabled until the form is valid.

Build this form with GolemUI (React). Ground yourself in the real GolemUI API through the GolemUI MCP — GolemUI's recommended channel — and write it with GolemUI's typed gui.* TypeScript builder (verified through the MCP), not a raw JSON schema.

Build it into a fully functional, runnable app — scaffold the project, wire it all up, and verify it compiles and runs.

We ran the benchmark with Claude: Opus, Sonnet, and Haiku. AIs aren't deterministic, so the same prompt won't produce identical code twice: your output will vary run to run, and other models may land elsewhere. Grounding through the MCP is what keeps results consistent.

Step 3 — What good looks like

Section titled “Step 3 — What good looks like”

You’ll know the grounding did its job when:

  • The form is authored with the typed {gui.} builder, e.g. one gui.inputs.* call per field, not a hand-written JSON blob.
  • It verified before presenting. With the MCP connected you’ll see dx_list_factories and dx_check_code in its tool log; with the skill alone, a npx -y @golemui/gui-mcp check-dx run in its terminal output. Either way it fixed what was flagged and re-checked.
  • The app compiles, the form renders, and the validation actually works.

Going further

Section titled “Going further”
  • Agent Skill — what’s in the skill, how it changes the agent’s behavior, and how to keep it updated.
  • Form Studio — an AI-assisted, low-code form builder. A free open-source community edition runs on Cloudflare Workers with just an Anthropic API key; the hosted Pro edition adds accounts and storage.
  • Tools reference — every MCP tool’s inputs, outputs, and when to reach for each.
  • llms-gui-dx.txt — the same complete {gui.} reference the skill ships, as a single file an assistant can read in one pass. The docs-channel fallback for assistants that can install neither the skill nor the MCP.

Troubleshooting

Section titled “Troubleshooting”
  • It wrote raw JSON instead of the typed builder. Ask it to use the {gui.} builder. Both validate against the same schemas, but the typed builder is smaller and easier to review — and it’s what you’ll want to maintain.
  • It used a widget or prop that doesn’t exist. The assistant isn’t grounded. Confirm your setup is live (npx skills list, or claude mcp list / Verify), then retry.
  • It never called the MCP. Make sure the server shows as connected and the tools are visible in the assistant, then restart your IDE. Telling it explicitly to “use the GolemUI MCP” helps.
  • The skill didn’t ask which API I wanted. It probably isn’t loaded — agents pick skills up at startup, so restart it after installing, and check npx skills list.
  • Build errors. Install the framework package (npm i @golemui/gui-react, -vue, -angular, or -lit) and import the styles once: @import '@golemui/gui-components/index.css';.