AI agents: AGENTS.md and DESIGN.md
The two files Local ships for Shopify Sidekick and AI coding agents: what AGENTS.md and DESIGN.md hold, and how to keep your own changes safe.
Local 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 Local is built: the four color zones (header, main, cards and footer) and the section colors that override them, the two fonts, the sections and blocks, and features such as the store selector and events. 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 Local looks: the design rules every preset shares, one part for each preset (Local, Soleway, Thrive, Caffeine and Lively), and short recipes for the section header, product card, buttons, forms, header, footer, the store selector and the event card. 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 Local'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 Local.
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 Local?
An update installs the new version of Local 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 Local.
Related pages
- Custom CSS and code: where custom CSS goes and what survives an update.
- Colors: the color zones the files refer to.
- Store selector: the feature the files describe for agents.
- Custom work and code changes: what Krown support covers.
Hide purchase buttons when local pickup is not available
A Local code tweak that hides the buy buttons when the product is not available at the store the customer selected.
What's new in Local
What's new in Local: every release of the theme on the Shopify Theme Store, with its date and the release notes, grouped by major version.