AI agents: AGENTS.md and DESIGN.md
The two files Seventh ships for Shopify Sidekick and AI coding agents: what AGENTS.md and DESIGN.md hold, and how to keep your own changes safe.
Seventh 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 Seventh is built: the color schemes and which part of the page uses each one, the three fonts and the accent word, cards and blocks, the class names 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 Seventh looks: the design rules every preset shares, one part for each preset (Seventh, Nora, Oak and Orim), and short recipes for the section header, product card, buttons, forms, 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 Seventh's style. For example, it changes a section's color scheme 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 Seventh.
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 Seventh?
An update installs the new version of Seventh 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 Seventh.
Related pages
- Custom CSS and code: where custom CSS goes and what survives an update.
- Colors: the color schemes the files refer to.
- 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 Seventh: where to add CSS, how to add code to the head or a custom font, and what survives a theme update.
What's new in Seventh
What's new in Seventh: every release of the theme on the Shopify Theme Store, with its date and the pages that describe each change.