Customizing with AI Agents
Break ships with the files AI coding agents look for when they open a project, and with a set of documents that describe how the theme is built. Open the theme folder in the tool you already use and describe the change in plain words. The agent finds the rules and recipes on its own, then rebuilds and checks the theme before it hands it back.
No access to anything private is needed. Everything the agent has to read, build and check is inside break.zip.
What's in the Theme Folder#
| Path | What it is for |
|---|---|
AGENTS.md | The entry point. What to read before editing which files, the commands, the rules of the theme and a map of the folders. Read natively by Codex, Cursor, GitHub Copilot, Windsurf, Zed, Jules, Amp and other tools that follow the AGENTS.md standard. |
CLAUDE.md | Points Claude Code, which looks for this file name, to AGENTS.md. |
GEMINI.md | Points Gemini CLI to AGENTS.md. |
docs/pd/ | How a Prime Direction theme is put together: the build, CSS and JavaScript conventions, Ghost's rules and limits, and step-by-step recipes, such as adding a front page section, a style for a section, a color scheme or a translation. |
docs/break/ | What is specific to Break: every setting, keyword, internal tag and page slug, every front page section and where its data comes from, and a map of the files. |
scripts/, rollup.config.mjs, linter configs | Everything needed to rebuild the theme's styles and scripts and to package a new zip. |
Supported Tools#
| Tool | Reads |
|---|---|
| Claude Code | CLAUDE.md, which leads to AGENTS.md |
| Gemini CLI | GEMINI.md, which leads to AGENTS.md |
| Codex, Cursor, GitHub Copilot, Windsurf, Zed, Jules, Amp | AGENTS.md |
Anything else that reads AGENTS.md | AGENTS.md |
Every tool ends up reading the same AGENTS.md, so it does not matter which one you pick, or if you switch between them.
Set Up Once#
- Unzip
break.zipinto a folder on your computer - Install Node.js 22 or newer
- In the theme folder, run
npm ci - Open the folder in your agent, as a project in Cursor, Zed or VS Code, or by starting Claude Code, Codex or Gemini CLI inside it
The install command in full, for copying:
npm ci
A warning about pd is expected. The theme's shared library is listed as
an optional package that lives in a private repository. npm skips it with a
warning, and the build uses the copy of the library already included in the
theme. Do not add --omit=optional to the command. It also leaves out parts
of the build tools the theme needs, and the build fails.
Ask for a Change#
Describe what you want the way you would describe it to a developer. A few requests the theme's documents are written to cover:
- Move the Watch section before the desks on the front page
- Add a fifth look for the featured post
- Translate the theme to Italian
- Add a dark green color scheme
The agent reads AGENTS.md, opens the recipe that matches the request in docs/, edits the templates, styles or translation files, and runs the theme's own checks before it reports back. Before it changes a theme setting, the routes.yaml file, a translation key or the default value of Disabled features, it asks you first.
Theme settings are limited. Ghost allows a theme at most 20 custom
settings, and Break uses 17. New on and off options are therefore added
as keywords of the Disabled features setting, and behavior for a single
post or page through internal tags and page slugs. The agent knows this from
docs/ and picks the right one.
Break already ships with German, Spanish, French and Portuguese translations next to English.
Check and Package#
The theme carries two commands the agent runs for you, and that you can run yourself:
npm run verify
Lints the styles and scripts, rebuilds the theme, runs Ghost's own gscan validator and checks the documents in docs/. The gscan check is the same one Ghost runs when a theme is uploaded.
npm run package
Builds the theme, updates the English translation file, makes a fresh break.zip and validates it. Upload that file in Settings → Design → Change theme → Upload theme, exactly as described in the Getting Started guide.
To see a change before it goes live, run Ghost on your own computer by following Ghost's local install guide, or upload the zip to a staging site first.
Keep the original zip. Your content, Ghost settings and the values in Design → Customize → Theme are not affected by uploading a modified theme, but the theme files themselves are replaced. Keeping the original download makes it easy to go back.
When the Theme Updates#
A new release of Break is a new zip, and it does not know about the changes an agent made to the previous one. To carry them over, unzip the new release into its own folder, open it in your agent and describe the same changes again, or hand it both folders and ask it to move your changes across. The Update Guide explains what an update replaces and what it keeps.
Good to Know#
- The agent never renames or removes a setting or an option label, so values saved in Ghost keep working
- The theme is checked against Ghost's validator before it is packaged, so a zip that fails to upload should not happen. If one does, contact us with the request you made
- The agent can explain any part of the theme. Ask it "how does the front page decide which desks to show?" and it answers from
docs/