Agent Skill

The GolemUI skill is an installable bundle of instructions and API reference that teaches an AI coding agent how to build GolemUI forms correctly. It works in any skills.sh-compatible agent and needs no server, no connector, and no configuration.

It exists because GolemUI shipped after every current model’s training cutoff. Without grounding, an assistant invents widget kinds and prop names that look plausible and break at runtime. The skill closes that gap through the docs channel; the MCP server closes it through tools. They’re designed to work together — see Skill or MCP? below.

Install

npx skills add golemui/golemui

That installs the skill project-locally into ./.agents/skills/golemui and wires it into whichever supported agents it detects — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Antigravity, Junie and others. Add -g to install at user level instead, so it’s available in every project:

npx skills add golemui/golemui -g

The installer also writes a skills-lock.json pinning the exact version it fetched. Commit it, and teammates can restore the same skill with npx skills experimental_install. To pick up a newer release later, run npx skills update golemui.

Skills run with your agent's permissions

The installer prints this reminder for every skill, ours included: review a skill’s contents before you use it. The GolemUI skill is plain Markdown — instructions and API reference, no executable code — and you can read every file in the repository before installing.

What’s inside

A SKILL.md entry point plus eight reference files the agent loads on demand, so it reads only what the current task needs:

Reference	Covers
forms-dx.md	The complete gui.* TypeScript builder — every factory with a compile-verified example
forms-json.md	JSON form definitions, and generating them from JSON Schema or OpenAPI
framework-setup.md	Installing packages, rendering the form, and receiving submits in each framework
widgets-index.md	The widget catalog, with a docs URL per widget for exhaustive options
features.md	Validators, states, events, i18n, interpolation, dependencies, loaders, item renderers
extending.md	Custom widgets, item renderers, validators, and middlewares
styling.md	Theming, CSS customization, headless rendering
mcp.md	Setting up and using the MCP server and its CLI

forms-dx.md is generated from the same compile-verified registry that backs the MCP’s dx_list_factories tool, and it’s regenerated on every GolemUI release. The skill and the MCP therefore describe the same API — they can’t drift apart.

How it changes the agent’s behavior

It asks which API you want. GolemUI forms can be authored as typed gui.* TypeScript or as a JSON definition. The skill treats this as a hard gate: unless your prompt already says which one, the agent stops and asks rather than picking silently. Answer once and it writes the whole form in that flavor.

It front-loads the failure modes that compile cleanly and then break. Wrapping formDef instead of passing the bare array (renders blank, no error), spreading include/exclude onto a factory result (silent no-op), the three-case validator type rule, and the per-framework submit event name — all stated up front rather than discovered at runtime.

It refuses to present unverified work. The skill ranks verification: MCP tools when they’re connected, otherwise the @golemui/gui-mcp CLI (check-dx / validate-json), which needs nothing installed beyond Node. Only when neither is reachable does it fall back to following its own rules unaided.

Skill or MCP?

They solve different halves of the problem, so the question is usually “which do I install first?” rather than “which one?”.

The skill is the knowledge and behavior layer: what the API is, which mistakes to avoid, when to ask you a question. The MCP is the verification and generation layer: deterministic tools that type-check real code, validate a definition against the shipped schemas, and map a JSON Schema or OpenAPI operation to a form.

• Skill + MCP — the strongest setup. The agent writes from the skill and verifies with MCP tools in the same turn.
• Skill alone — the zero-config setup, and the one that works in the most agents. Verification falls back to the CLI, which is the same checker without the connector.
• MCP alone — tools without the authoring rules. It catches broken code, but the agent needs more attempts to get there.

Tip

Installing both is one command each and they compose automatically — the skill detects the MCP tools and prefers them.

Verify it’s working

Ask your agent to build something small and watch for the tell: it should ask whether you want the TS or JSON API before writing any form code. That question is unique to the skill — an ungrounded assistant just starts typing.

You can also confirm the install directly:

npx skills list

Next steps

• Getting started with AI — from install to your first AI-built form.
• MCP Server — add deterministic validation and schema-to-form generation.
• llms.txt — the docs index for assistants that can’t install either.