AI agents: AGENTS.md and DESIGN.md
The two files Highlight ships for Shopify Sidekick and AI coding agents: what AGENTS.md and DESIGN.md hold, and how to keep your own changes safe.
Highlight 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 Highlight is built: the background, text and accent colors and the section colors that override them, the three fonts, the twelve-unit grid and the two spacing settings, the sections and blocks, and the settings that control each part. 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 Highlight looks: the design rules every preset shares, one part for each preset (Highlight, Single and Brush), and short recipes for the section header, product card, buttons, header and footer. 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 Highlight's style. For example, it changes 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 Highlight.
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 Highlight?
An update installs the new version of Highlight 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 Highlight.
Related pages
- Custom CSS and code: where custom CSS goes and what survives an update.
- Colors: the three colors the files refer to.
- Typography: the three fonts.
- JavaScript events: events for apps and custom scripts.
- Custom work and code changes: what Krown support covers.
Custom CSS and code
Custom CSS and code in Highlight: where to add CSS or Liquid without editing theme files, custom fonts, and what survives a theme update.
What's new in Highlight
What's new in Highlight: every release of the theme on the Shopify Theme Store since 2021, with its date and links to the release notes.