Working with AI Agents

The theme folder you download is a complete project: templates, source styles and scripts, an npm build, and Ghost’s own validator. It also contains AGENTS.md, a short file that AI coding agents read before they touch anything.

If you do not see AGENTS.md in your folder, download the latest version of Essence from your Lemon Squeezy orders.

What the agent learns from it

• The commands to install, build, and package the theme.
• That gscan, the validator Ghost uses to accept a theme, has to pass before a change is done.
• Which files are generated and must not be edited by hand.
• That assets/custom.css and assets/custom.js survive a theme update, while the source files need a build.
• That routes.yaml is uploaded separately in Ghost admin.
• That the uploaded package has to keep its name, or Ghost resets your Design & Branding settings.
• Where the documentation index for Essence lives, so the agent can look up any feature.

That last point is what saves the most time. Ask for something the theme already does and the agent reads the page that explains the setting, instead of writing code for a feature you already paid for. The index is fetched from this site, so it is current even for a theme folder you downloaded a year ago.

AGENTS.md is the convention Cursor, Codex, GitHub Copilot, Gemini CLI, and Zed read. Claude Code reads CLAUDE.md, which ships next to it and points at the same file.

Getting started

1. Unzip the theme somewhere you can work in.
2. Run git init and commit the untouched theme. This one step is what lets you keep your changes when an update arrives — see Updating Theme.
3. Open the folder in your agent: claude or cursor . in that directory.
4. Ask for what you want. The agent reads AGENTS.md on its own.

Requests that work well

Make the site wider on large screens.

Add a table of contents to posts.

Translate the theme into German.

I want the sidebar collapsed by default.

Each of these is already a documented setting in Essence, and the agent will find it rather than write new code.

Change the post card so the author avatar sits above the title, then run the build and gscan.

That one is a real code change, and naming the check tells the agent when it is finished.

Uploading the result

Ask the agent to run npm run build:prod. It rebuilds the assets and writes essence.zip, ready to upload in Settings → Theme → Upload theme. Keep the file name as it is.

Reading the documentation yourself

The same documentation is published in a form built for machines, which is useful with an assistant that cannot open a browser.

• Every page of the Essence documentation, each with a description: /docs/essence/llms.txt
• Any page as Markdown: add .md to its address, for example /docs/essence/introduction.md
• Every page of every theme, if you work across more than one: /docs/llms.txt

When not to use an agent

For a colour tweak or a small style override, Code Injection in Ghost admin is faster and survives every theme update untouched. Reach for an agent when a change needs the template files themselves.