AI agents: AGENTS.md and DESIGN.md
The two files Kingdom ships for Shopify Sidekick and AI coding agents: what AGENTS.md and DESIGN.md hold, and how to keep your own changes safe.
Kingdom ships two text files at the root of the theme for AI tools: AGENTS.md and DESIGN.md. Shopify Sidekick reads them when you ask it to change your store's look in the theme editor, and coding agents such as Claude Code, Cursor or Codex read them when a developer works on the theme code.
Where to find it: Shopify admin → Online Store → Themes → … → Edit code, at the top of the file list.
What the two files hold
AGENTS.mdexplains how Kingdom is built: how the files are organized, how the sidebar, the color zones and the type scale work, the sections and blocks, and the mistakes to avoid. It is written for agents, so they change your store the way the theme expects, and it ends with a list of every section and block in the theme.DESIGN.mddescribes how Kingdom looks: the design rules every preset shares, one part for each preset (Kingdom, Queen and Prince), and short recipes for the section header, product card, buttons, header, footer, the hero slider and the marquee. It names the Theme settings that carry each color and font, never raw values.
How Sidekick uses them
- Sidekick reads both files before it suggests a design change, so its suggestions stay in Kingdom's style. For example, it changes a zone color or a section's own colors instead of coloring one element by hand.
- When you ask Sidekick to change the style of your store, it can update
DESIGN.mdwith the new direction. Your own rules stay in the file. - The list of setting and token names at the top of
DESIGN.md, between the two marker lines, is written by Krown. Leave it as it is; the rest of the file is yours to grow.
Custom CSS from Sidekick or an agent belongs in the section's Custom CSS setting, at the bottom of the section's settings in the theme editor, or in Theme settings → Custom CSS for a rule that applies to the whole store. Don't let an agent edit assets/theme.css or add new files to assets: those files are rebuilt by Krown and replaced when you update Kingdom.
Do I need to do anything?
No. The files come with the theme and work as they are. Edit DESIGN.md only if you want to record your own design rules, for example a color or a layout you never want changed. You can also delete both files: the theme works the same, and AI tools then work from the theme code alone.
What happens to the files when I update Kingdom?
An update installs the new version of Kingdom as a separate theme, with Krown's fresh AGENTS.md and DESIGN.md. A DESIGN.md you edited stays in the old copy, so copy your own rules into the new file after you update. See Update Kingdom.
Related pages
- Custom CSS and code: where custom CSS goes and what survives an update.
- Colors: the color zones the files refer to.
- JavaScript events: events for apps and custom scripts.
- Custom fonts: load your own fonts with code.
- Custom work and code changes: what Krown support covers.
Custom fonts
How to load your own font files or a Google font in Kingdom with code: the font-face rules and the font variables in head-variables.liquid.
What's new in Kingdom
What's new in Kingdom: every release of the theme on the Shopify Theme Store, grouped by major version, with its date and the pages it changed.