Skip to main content
Prime Direction

Customizing with AI Agents

Wire ships with the files AI coding agents look for when they open a project, and with a small knowledge base describing how the theme is built. Open the theme folder in the tool you already use, describe the change in plain words, and the agent finds the rules and recipes on its own — then rebuilds and checks the theme before handing it back.

No access to anything private is needed: everything the agent has to read, build and check is inside wire.zip.

What's in the theme folder#

PathWhat it is for
AGENTS.mdThe entry point. What to read before editing what, 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.mdThe same instructions for Claude Code, which looks for this file name.
GEMINI.mdThe same instructions for Gemini CLI.
docs/The knowledge base: how the theme is put together, CSS and JavaScript conventions, Ghost gotchas, and step-by-step recipes — add a section, add a style to a section, a colour scheme, a translation, an override.
scripts/, rollup.config.mjs, linter configsEverything needed to rebuild the theme's styles and scripts and to package a new zip.

Supported tools#

ToolReads
Claude CodeCLAUDE.md
Gemini CLIGEMINI.md
Codex, Cursor, GitHub Copilot, Windsurf, Zed, Jules, AmpAGENTS.md
Anything else that reads AGENTS.mdAGENTS.md

The three files carry the same instructions, so it does not matter which tool you pick — or if you switch between them.

Set up once#

  1. Unzip wire.zip into a folder on your computer
  2. Install Node.js 22 or newer
  3. In the theme folder, run npm ci --omit=optional
  4. 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 --omit=optional

Why --omit=optional: the theme's shared library is listed as an optional dependency and lives in a private repository. The flag skips it, and the build uses the copy of the library already included in the theme. Without the flag the install still works, but Git may ask for credentials you do not have.

Ask for a change#

Describe what you want the way you would describe it to a developer. A few requests the theme's docs are written to cover:

  • Add a video section to the homepage, after the featured posts
  • Center the hero and make the title larger
  • Translate the theme to German
  • Add a dark green colour scheme

The agent reads AGENTS.md, opens the recipe that matches the request in docs/, edits the templates, styles or locale files, and runs the theme's own checks before it reports back. When a request touches something the theme cannot change safely — the routes.yaml file, an existing theme setting, a locale key — it asks first.

Theme settings are limited: Ghost allows a theme at most 20 custom settings. Rather than spend them, new options are usually added through the existing Additional features keywords, internal tags and page slugs — the agent knows this from docs/ and picks the right mechanism.

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 and runs Ghost's own gscan validator — the same check Ghost performs when a theme is uploaded.

npm run package

Builds a fresh wire.zip and validates it. Upload that file in Settings → Design → Change theme → Upload theme, exactly as described in the Getting Started guide.

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 Wire 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#

  • Settings, option labels and locale keys are never renamed by the agent, 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 featured section choose its style?" and it answers from docs/