Building with AI

Studio ships skills: structured, versioned guides that teach a coding assistant how to build on Studio — the concepts, the YAML shapes, the traps, and the checks to run. With the skills installed, you describe what you want and the assistant writes the automation, the agent and the package files in the shapes this documentation describes, then deploys and verifies them.

The skills are plain Markdown folders. They are written for Claude Code, and work with any assistant that reads a project’s skill or instruction folders.

Install the skills

The bundle is published with every Studio release:

mkdir -p .claude/skills
curl -sL https://assets.studio.maravilla.cloud/studio-skills.tar.gz | tar -xz -C .claude/skills
ls .claude/skills

Each studio-* folder is one skill with a SKILL.md and references. The assistant loads a skill when your request matches its description; you can also invoke one by name.

Keep the bundle current: re-run the install after a Studio update. A skill describes the version it ships with.

A session that builds an automation

With the skills in place, a request like this produces a working package:

In our package, add an automation: when a studio:Page in stories is updated, ask the content reviewer agent whether the description is good enough; if not, create a task for the page’s owner with the agent’s suggestion. Ship it disabled. Deploy it to my local repo and run it once against /campaign/about.

The assistant, following studio-automations, will:

1. write content/automations/<slug>/.node.yaml with the trigger, an agent step with a structured answer, a person task, and the connections;
2. write or reuse an agent under content/functions/agents/;
3. validate the package, deploy it, and read the automation’s compile verdict back from the tenant rather than trusting the deploy output;
4. run it with the page as subject and read the run’s step outputs, so what it reports is what happened.

Ask for the same thing in the editor instead — “walk me through building it in Studio” — and the skill’s editor section is what it follows.

What the skills know that this documentation summarises

The skills are the long form. Where a page here says “narrow the trigger with paths”, the skill says why * does not cross a folder, what the engine matches before a run exists, and what a mount’s sync actor looks like on a node. Where the Variables page lists shapes, the skill explains which engine step produces each and how to verify it on a real run. When something surprising happens, the skill’s traps sections are the first place to look.

Working conventions

• Content over code. Prefer an automation, an agent and library steps to a custom function. Write a function when the work is deterministic and reusable, and give it an input and output schema so it becomes a step and a tool.
• Ship off, switch on. Automations in a package ship enabled: false; a tenant enables what it wants.
• Own your roots. Name the content roots your package owns in .raisin-sync.yaml, so your re-deploys replace your automations and leave a customer’s edits alone.
• Verify on the tenant. After a deploy, the assistant should read the automation’s compile verdict and, for a change in behaviour, run it once. “Deployed successfully” says the package was accepted, not that the automation compiles.