AI agents
If you use an AI coding agent, such as Claude Code, it can do most of the work of setting up a website for Surreal CMS. Our agent skill teaches it how. With the skill, an agent can add content regions to your pages and check them for problems. Give it a token, and it can also create the site, enable its pages, and invite your client.
A skill is a folder of instructions, reference docs, and scripts that an agent reads when a task calls for it. Ours covers the same material as these docs, written for an agent to follow, and it's checked against the code that runs Surreal CMS.
What you can ask it to do
Integration work doesn't need an account. The agent edits your HTML files and checks them.
- “Make the pages in this folder editable in Surreal CMS. Keep the layout locked.”
- “Turn the team section into repeatables so my client can add people.”
- “Move the header and footer into includes.”
- “Check every page for Surreal CMS problems and fix them.”
With access to your account, it can set things up in Surreal CMS too.
- “Build a site for Acme Bakery with Home, Menu, and Contact pages, and let bob@acmebakery.com edit it.”
- “Give Bob access to the new pricing page.”
- “Add a callout block and an FAQ block to the Acme site.”
For a request like the first one, the agent builds the pages with content regions, puts them on your server, creates the site, enables the pages, invites Bob, and gives Bob access. Then it tells you what it did and what's left for you to do in the app.
Installing the skill
The skill lives on this website at https://www.surrealcms.com/skills/surreal-cms/. The simplest
way to use it is to point your agent at it in your request. The agent reads the latest version every time.
Read https://www.surrealcms.com/skills/surreal-cms/SKILL.md and use it to make this website editable in Surreal CMS.
To make the skill available without asking, save its files to your agent's skills folder. For Claude Code, this command installs it for every project.
curl --create-dirs --output-dir ~/.claude/skills/surreal-cms -o "#1" \
"https://www.surrealcms.com/skills/surreal-cms/{SKILL.md,references/integration.md,references/connecting.md,references/api.md,scripts/check.py}"
To install it for one project, change ~/.claude/skills to .claude/skills and run
the command in the project's folder. Other agents that support skills use their own folder, so check
your agent's docs to find it.
An installed copy doesn't update itself. Run the command again to get the latest version. The version
number is at the top of SKILL.md.
What's in the skill
The agent reads SKILL.md first, then the reference that matches the task. The files are plain
text, so you can read them too.
| File | Contents |
|---|---|
| SKILL.md | What the API can and can't do, the rules the agent follows, and the steps for building a site and handing it to a client. |
| references/integration.md | Content regions, repeatables, lockables, includes, metadata, scripts that misbehave in the editor, and a checklist for before a site goes live. |
| references/api.md | Every API route the agent can use, with its fields, error codes, and common mistakes. |
| references/connecting.md | The fields for each protocol, folder formats, and what to check when a connection fails. |
| scripts/check.py | A checker that finds integration problems in HTML files. |
Checking pages for problems
The checker flags the same problems the source editor underlines, plus a few more that break publishing. It finds duplicate ids, regions without ids, regions on elements that can't hold them, inline SVG and custom elements that the editor strips, and server-side code inside regions. The agent runs it before any page goes live.
You can run it yourself, too. It needs Python 3 and nothing else.
python3 check.py *.html
It prints each problem with the file and line number.
index.html:3: error: Duplicate id "intro" (first used on line 2).
index.html:4: error: <div> has cms-editable but no id.
Fix every error before you enable a page. Warnings point at things that might not work the way you expect. The checker exits with status 1 when it finds an error, so you can also run it in a build or CI step.
Letting it use your account
To work in your account, the agent needs an agent token. Agent access is part of every paid plan. Create the token under Users > Edit Profile > Security & Access > Agent Access. You choose whether the agent may invite people and manage their access, and whether it may delete things. The token is shown once, so copy it right away.
Treat it like a password. The agent reads it from an environment variable named
SURREAL_AGENT_TOKEN. Never put it in your code, in a .env file inside a project,
on a command line, or in your chat.
If you use Claude Code
Add it to ~/.claude/settings.json, creating the file if it doesn't exist. Claude Code
reads this file however it's started, so it works in the terminal, in the desktop app, and in VS Code.
A line in your shell profile does not: the desktop app and VS Code don't see variables you export
there.
{
"env": {
"SURREAL_AGENT_TOKEN": "your-agent-token-here"
}
}
If you use Codex, Cursor, Gemini CLI, Copilot, or another agent
These agents inherit the environment of the shell they start from, so add the variable to your shell profile
and open a new terminal. On a Mac the profile is ~/.zshrc; on Linux it's usually
~/.bashrc.
export SURREAL_AGENT_TOKEN="your-agent-token-here"
On Windows, run this once in PowerShell, then open a new terminal.
[Environment]::SetEnvironmentVariable("SURREAL_AGENT_TOKEN", "your-agent-token-here", "User")
Codex blocks network access in its default sandbox, so the agent's requests fail until you turn it on:
set network_access = true under [sandbox_workspace_write] in
~/.codex/config.toml. Cursor reads your profile when it starts, so restart it after adding the
line.
Check that it worked
Open a new terminal and print the variable: echo $SURREAL_AGENT_TOKEN on a Mac or Linux, or
$env:SURREAL_AGENT_TOKEN in PowerShell. If it prints your token, every agent you start from
that terminal has it. If it prints nothing, the profile line didn't save, or you're in a window
that was open before you added it. For Claude Code, the settings file is read on every start, so
there's nothing to check.
Then give your agent a prompt that points at the skill:
Read https://www.surrealcms.com/skills/surreal-cms/SKILL.md and use my Surreal CMS agent token to set up this website.
Whatever the switches say, an agent can never create or change admins, set passwords, change email addresses, or read your hosting credentials. Everything it does appears in the activity log as your work, marked via agent. The skill also tells the agent to confirm with you before it sends an invitation or deletes anything, and to look for an existing site, page, or user before creating one.
To cut off access, select Disable Agent Access on the same screen. It revokes the token right away. The account owner can also turn off Allow AI agents under Settings > Advanced, which pauses every agent on the account without removing anyone's token.
A Personal Access Token in SURREAL_PAT works too, on the Agency plan or
higher. It isn't held to all the agent rules above: it can still change clients' emails and
passwords, edit admins, and read hosting credentials, so prefer an agent token for an agent.
What it can't do through the API
The API can't publish, edit the source of a page that already exists, upload images or other files, test a connection, or create admins. When the agent needs one of those, it tells you where to do it in the app.
That's why the agent gets the HTML right before it enables a page. Surreal CMS doesn't host your website, so you publish the files to your host the way you normally would, or ask the agent to use your usual deploy. Once the pages are live, the agent adds the site and enables them.
Before you hand off the site
Open each page in the visual editor before you invite anyone. Hover over the content to see the guides, which show what your client will be able to edit. Then publish a small change and look at the live page. It's the same thing we'd suggest if you set up the site by hand.
If the skill gets something wrong, please let us know so we can fix it.