Working with AI agents

Most buyers customize a theme with a coding agent now. Without guidance an agent spends its first thirty tool calls mapping the repository, then flattens the design while “cleaning up”. Themes marked Agent-ready on their theme page ship two files at the root to prevent that:

• AGENTS.md, the instructions. Claude Code, Cursor, Copilot and Codex all read this name.
• CLAUDE.md, two lines that point at AGENTS.md for tools that look for that name first.

What is in AGENTS.md

Every file follows the same shape, written for that specific theme:

Section	What it gives the agent
What this is	Stack, where content lives versus where design lives, the build command and the exact page count it must produce
Where things live	A file map: config, collections, components, scripts, styles
Task map	A table from “the client wants X” to “edit file Y”, so the agent does not explore first
Traps	The things that break this theme silently: hidden-until-JS reveals, prefixed classes, duplicated palettes, closed provider enums, locale mirrors
Design invariants	The decisions that are the product, marked do-not-touch unless the client asks
Before you say you are done	Build, page count, the pages to scroll, what to check in both color modes

The file is design protection first and documentation second. Everything a human needs is in these docs. AGENTS.md exists so the agent gets the edit right on the first pass.

How to use it

Claude Code

Open the theme folder and start Claude Code. It reads CLAUDE.md, which sends it to AGENTS.md. Nothing to configure.

cd my-theme
claude

Then ask for the change in plain language:

Change the studio name to "Atelier Nord", swap the accent to #1d4ed8,
and add a fourth service called "Landscape" with the copy from brief.md.

Cursor, Copilot, Codex

All three read AGENTS.md from the repository root automatically. If your tool asks for a rules file, point it at AGENTS.md.

Any other tool

Paste AGENTS.md into the system prompt or the first message. It is written to be read cold.

What to expect

• The agent edits src/config/site.ts for copy and global.css tokens for color, not components.
• It leaves the signature interactions alone: the hero rig, the stacking deck, the marquee, the lightbox, the accent switcher.
• It runs the build and reports the page count before it says it is done.
• If it needs to touch a trap, it tells you which one and why.

Keeping the file true

AGENTS.md describes the theme as shipped. If you rename folders, move the config or change the palette mechanism, update the file in the same commit. A stale AGENTS.md is worse than none, because the agent trusts it.

Themes that ship it

Axial, Form Lab, Sable, Moxie, Contour, Project Go, Plinth, Nerve, Tally, Vertex and August. Look for the Agent-ready badge on the theme page.