AI agents: AGENTS.md and DESIGN.md
The two files Split ships for Shopify Sidekick and AI coding agents: what AGENTS.md and DESIGN.md hold, and how to keep your own changes safe.
Split 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 Split is built: the half-screen box layout, the header, body and sidebar colors, the two fonts, 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 Split looks: the design rules every preset shares, one part for each preset (Split, Drawer and Nomad), and short recipes for the section header, product card, buttons, forms, header, footer, the split-screen slideshow and the collection page. 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 Split'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 Split.
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 Split?
An update installs the new version of Split 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 Split.
Related pages
- Custom CSS and code: CSS recipes and where custom CSS goes.
- 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 for Split developers: custom fonts, extra product badges and header layout recipes. Krown support does not help with custom code.
What's new in Split
What's new in Split: every release of the theme on the Shopify Theme Store since 2017, with its date and the pages that describe each change.