Skip to main content

Working with AI agents

A design system in files is a design system a coding agent can work on. The parts that make that safe are already there: JSON Schemas describe every file, better check gives a fast pass/fail with the offending path, better ds dev renders locally so changes can be looked at, and better ds push cannot reach Live on its own.

What an agent still needs is the conventions — the ones no schema encodes. Which prefix addresses which namespace. That a module's first Liquid tag must not left-trim. That setting keys are unique across the whole design system and ids are identity. The CLI ships that knowledge as files you install into your repository.

Install the teaching files​

better ai-files install

This writes two things into the current directory:

  • AGENTS.md — the section most coding agents read on startup. If the file does not exist it is created; if it does, only the region between the <!-- better-email:ai-files:begin --> and <!-- better-email:ai-files:end --> markers is replaced. Anything you wrote outside those markers is left exactly as it was, so the file is yours and the section is ours. A file that has no markers yet gets the section appended.
  • .claude/skills/better-email-design-systems/SKILL.md — the same guidance as a Claude Code skill, so it loads when the task calls for it rather than sitting in context all the time.

Run it again after upgrading the CLI to refresh both. The skill file is wholly generated and is overwritten in place; if you have replaced it with your own version, the command stops rather than discarding your work.

better ai-files --help lists the subcommands.

npm create better-email already writes the AGENTS.md section when it scaffolds a repository, in the same markers, so a later better ai-files install updates it cleanly.

Keep them current in CI​

better ai-files install --check

Writes nothing and exits 1 when the files are missing or out of date against the CLI you have installed. Run it in the same job as better check and a CLI upgrade that changes the guidance shows up as a failing build instead of an agent working from last year's conventions.

What the files teach​

The content is one document covering what someone editing the tree needs to know and cannot infer:

  • the managed layout — design-system.json, base.liquid, settings.json with its canonical Global and Shared settings, modules/<key>/, modules.order, and the .better/config.json binding — and the invariants the CLI enforces;
  • the loop, with exact commands: better ds pull, better check, better ds dev, better ds diff, better ds push, including staging semantics and what --force means after the remote has moved;
  • the Liquid conventions — addressing, repeatable iteration, image and link value shapes, rich text passing through unescaped, and the whitespace-control rule that silently empties a module when broken;
  • that setting keys are unique design-system-wide and that the id is a module's identity, not its directory name;
  • when the project uses Maizzle or React Email, that the sources are what you edit and the output tree is generated;
  • where the schemas and these docs live.

Guardrails worth keeping​

The useful division is between what an agent can do freely and what a person decides.

Free: better check, better ds diff, and better ds dev all run locally, need no credentials, and change nothing on the platform. An agent can iterate against them as fast as it likes.

Ask first: better ds push creates a version in the shared history under whoever's session is signed in. It is recoverable — versions are append-only and nothing reaches Live — but it is visible to your team, so it is worth a human confirming.

Never: publishing to Live. No CLI command does it, so this one enforces itself.

Two habits make the rest work. Point the agent at better ds dev when the change is visual, because a design system that validates can still look wrong. And review the diff as a diff — Liquid and JSON in a pull request read like any other code, which is most of the reason for keeping the design system in a repository at all.