Build themes with AI agents

An AI coding agent (Claude Code, Codex, Cursor, Copilot and others) can build a Sneferu theme from a mockup or a brief. Sneferu gives it three things to work from, so it follows the same workflow and rules as a person reading these docs.

The quickest start is npm create sneferu my-theme (the same as npx sneferu init my-theme): the new folder already has its AGENTS.md, so open your agent in it.

AGENTS.md and CLAUDE.md at the top of a theme folder are not part of the theme: validate, build and push skip them, like README.md, so they never change the compiled theme.

What the agent is told

The theme's AGENTS.md is short and imperative. It lists:

1. The commands: dev to preview, format, validate, build, and push --dev-store only when you ask for it.
2. The files: what theme.json, the layout, templates, groups, sections, blocks, snippets, locales and assets are for.
3. The rules the compiler enforces (allowed markup, no JavaScript, no form controls, safe links) and the ones it cannot (everything merchant-editable, both text directions, accessible sizes and contrast).
4. What done means: validate clean, format --check clean, every page type checked in every locale at a desktop and a phone width.

Prompts to start from

Copy one, change the details, and attach the mockup if you have one.

A new theme from a mockup:

Create a Sneferu theme for a coffee shop from the attached mockup. Arabic and
English, Arabic first. Start with `npx sneferu init cafe-nile`, read the
AGENTS.md it writes, and follow it. Home page: hero, featured beans, subscription
plans, footer. Every page type must match the design. Finish when
`npx sneferu validate` and `format --check` are clean, and show me
screenshots of the dev preview at 1440 and 390 px in both languages.

A theme from a written brief:

Build a Sneferu theme for a handmade jewellery store: warm neutrals, a rounded
sans-serif, large product photos. Read https://hekana.dev/llms-full.txt first. Use the
starter (`npx sneferu init`), keep every text editable by the merchant,
and do not push anything.

One new section in an existing theme:

Add a "How it works" section to this Sneferu theme: a heading and three to five
steps, each with an hk-icon, a title and a sentence. Steps are blocks. All text
is localized settings with Arabic and English defaults. Add it to the home
template's default sections and run validate.

Start from an example design:

Run `npx sneferu init --list`, pick the template closest to a dark
gaming top-up store, scaffold it as `game-vault`, then change the colours and
fonts to the attached palette. Keep the page structure.

Push to your dev store (after npx sneferu login in your own terminal):

Bump the version in theme.json and push this theme with
`npx sneferu push . --package <id> --dev-store`. Then open the dev store
URL it prints and check the home, product and cart pages.

Review what the agent made

Before you push a theme an agent wrote, check:

Keep it current

AGENTS.md comes from the CLI version that ran init. After upgrading the CLI, compare yours with the one a fresh init writes, or point the agent at hekana.dev/llms-full.txt, which always follows the latest release.