Setting Up Surreal CMS with an AI Agent

By Cory LaViska on November 20, 2026

If you use an AI coding agent, you can hand it the work of getting a website ready for Surreal CMS. We've published a skill that teaches it how.

A skill is a folder of instructions, reference docs, and scripts that an agent reads when a task calls for it. Ours works with Claude Code and other agents that support skills. It covers the same material as our docs, written for an agent to follow.

The skill covers every type of content region, along with repeatables, lockables, includes, metadata, and scripts that misbehave in the editor. It knows the fields for each protocol and what to check when a connection fails. It knows every route in the developer API, and the mistakes that are easy to make, like forgetting that permissions are replaced instead of merged. It also has the agent check its work for the same problems the source editor underlines, plus a few more that break publishing.


Installing it

The skill lives on this website. The easiest way to use it is to point your agent at it.

Read https://www.surrealcms.com/skills/surreal-cms/SKILL.md and use it to make this website editable in Surreal CMS.

To install it for every project, save the files to your agent's skills folder. For Claude Code, that's ~/.claude/skills.

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}"

Things to ask it

You don't need an account for integration work. Try things like:

  • “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.”
  • “Check every page for Surreal CMS problems and fix them.”

Letting it use your account

With the developer API, an agent can go further. It can create the site, enable pages, add templates and blocks, invite your client, and set their permissions. For example:

  • “Build a site for Acme Bakery with Home, Menu, and Contact pages, and let bob@acmebakery.com edit it.”

Agent access is part of every paid plan. Create an agent token under Users › Edit Profile › Security & Access › Agent Access, where you also choose whether the agent may invite people and delete things. Treat the token like a password. Keep it in an environment variable, SURREAL_AGENT_TOKEN, and not in your code or your chat. The skill tells the agent to confirm with you before it sends an invitation or deletes anything. There's more on how it works in Connect Your AI Agent to Surreal CMS.

The API can't publish, edit the source of an existing page, upload images, or test a connection. The agent sets things up and tells you what's left to do in the app.


Check its work

Before you invite anyone, open each page in the editor yourself. Guides point out problems the agent can't see. Then publish a small change and look at the live page. It's the same thing I'd tell you to do if you set it up by hand.


For more prompts, including one that builds a new website from scratch, see building with your AI agent. The AI agents docs cover installing, updating, and running the checker in more detail. If the skill gets something wrong, please let us know so we can fix it.

So simple, it’s Surreal

Free for personal, educational, and non-profit websites.

By signing up, you agree to the terms of service.