Best practices

Prompting your AI agent to build a .gui file

gui setup teaches your own agent the format. Here’s the mental model and what to actually say.

.gui contains no AI. The CLI and the reference engine are 100% deterministic — validation, rendering, and scoring, zero model calls, by design (RFC-0010): a deterministic pipeline is one an agent can trust to mean exactly what it says. The actual design generation happens in your own agent — Claude Code, Gemini CLI, Cursor, Codex, whatever you already use. gui setup installs the dotgui skill into that agent, so when you ask it to build something, it already knows the format instead of guessing at markup.

The mental model

The loop

you ──ask──▶ your agent ──uses──▶ dotgui skill ──calls──▶ gui (this tool)

You ask in plain language. The skill tells your agent the format’s vocabulary, conventions, and pitfalls (see Common agent mistakes). The agent writes design.guix markup directly, then calls the gui CLI to validate and package it — gui never designs anything itself, it only checks and packages what the agent wrote.

Getting started

One-time setup

npm i -g @dotgui/cli
gui setup   # installs the dotgui skill into detected agents

gui setup asks for one confirmation and installs into each detected agent’s skill directory (e.g. ~/.claude/skills/dotgui/). After that, a plain-language ask is enough.

What to actually say

Say what the screen is for and let the agent choose structure: "a stocks watchlist screen, dark mode, one card per holding." The skill already knows the vocabulary — you don’t need to write markup yourself.

Don't

Don’t ask for "a screenshot" or "a mockup image" of the UI — that sends the agent toward pixels instead of a .gui file, and you lose everything covered in vs a screenshot or PNG mockup.

If you already have a reference — a competitor’s screen, a Figma file, a hand sketch — hand it over and ask for a .gui file built from it. The skill handles translating intent into the format’s elements, roles, and tokens.

Once you have a file, iteration is just more asks: "make the balance number larger," "use the brand token for the CTA fill." Each change is a targeted edit to the existing file, not a regeneration from scratch.

Frequently asked

Does gui setup work with any AI coding agent?

It installs the dotgui skill into detected agents — Claude Code, Gemini CLI, Cursor, Codex, and others with a skill/plugin model. For agents without one, it prints the format snippet to add manually.

Does the gui CLI itself generate designs?

No — the CLI and engine are 100% deterministic, zero AI. Your own agent does the designing; gui only reads, validates, lints, renders, and packages the result.

What should I say to my agent to get a .gui file instead of a mockup image?

Just ask for what the screen is for in plain language — after gui setup, the skill already tells the agent to produce a .gui file. Avoid asking for a "screenshot" or "image," which points the agent at pixels instead of structured markup.