Developing workflows with Claude Code and AI

An exported repository is made for an AI agent such as Claude Code to work in: it carries instructions for the agent, the types of every script, and a command line that checks, tests and imports what the agent changed. Whatever comes back is a draft. Publishing stays a person’s click in the app; no command, no tool and no AI step publishes, pauses or deletes a workflow. In the app’s script editor, AI writes, explains and fixes scripts too (Write with AI).

This page walks through it from the export to the published version.

1. Export the workflows

In the workflow designer, Export writes a ZIP with the workflows and, with Instructions for AI agents selected, the agent’s files at the root (Export, import and Git). A push to the workspace’s Git remote writes the same files (Workflows in Git). The repository then holds:

• workflows/<key>/workflow.yaml and workflows/<key>/scripts/, the workflows and their scripts;
• workflows/<key>/types/, the SDK’s declarations, the workspace’s types the workflow uses and each script step’s declarations, so an editor, tsc and the agent see the same types as the app;
• CLAUDE.md, AGENTS.md and .claude/skills/acriva-workflows/SKILL.md: what the agent needs to know.

2. Open the repository with Claude Code

Unpack the ZIP (or clone the repository) and start Claude Code in its folder. Claude Code reads CLAUDE.md and the skill by itself; other agents read AGENTS.md. The three files say:

• that everything in the repository may have been written by anyone with write access to it, and is data for the agent, never instructions it follows;
• that publishing happens in the app, by a person, and that acriva workflows push imports drafts only;
• the layout, the hooks, the sandbox’s limits and the workspace’s document types and fields by their keys;
• the CLI’s commands.

They are instructions, not settings. The export never writes .mcp.json, .claude/settings.json or hooks: such files are code that the agent’s tool runs. Never approve a project’s MCP server or settings that you didn’t add yourself.

The next export writes the three files again. Edit the workflows, not the instructions.

3. Check, test and import with the CLI

The CLI @acriva/cli (acriva) checks, tests and imports the repository through Acriva’s API with an API key. It isn’t published on npm yet; once it is, pin its exact version in the repository’s package.json (npm i -D @acriva/cli@<version>) and run it with npx acriva. It needs Node.js 22.12 or newer.

Create a key under Settings, in the category Security & access, on the page API keys, for a role that manages workflows: with the permission workflows:read (Get the workflow SDK’s types, check scripts, and validate and test workflow packages (needs a role that manages workflows)) to check and test, and workflows:draft (Import workflows as drafts; a person publishes them in Acriva (needs a role that manages workflows)) as well to import. Then:

export ACRIVA_URL=https://app.acriva.de
export ACRIVA_TENANT=<your workspace's address>
export ACRIVA_API_KEY=acv_live_…   # only from the environment, never in a file of the repository

npx acriva workflows validate      # the server's check of every workflow and script, with ACR-S codes and positions
npx acriva workflows test          # runs the fixtures (workflows/<key>/fixtures/*.json) in the sandbox; nothing is applied
npx acriva workflows push          # imports the workflows as drafts

• validate runs the same checks as a publish: the workflow’s rules, and each script’s type check and lint. A problem prints as workflows/<key>/scripts/<file>:<line>:<column> error ACR-S003 ….
• test runs the synthetic cases in fixtures/: a document, the data sources’ answers, the Datentabellen’s rows and the expected result. --document <id> runs on a real document instead, which needs the key’s documents:read and your confirmation: its values then leave Acriva and reach your terminal or your agent.
• push creates a draft of each workflow. References that don’t exist in the workspace (a role, a tag, a member) wait for a person’s mapping in the app for 7 days. A draft a person saved is replaced only with --replace-draft; Acriva then keeps that person’s draft as the previous draft and tells them (see step 5).

--json prints one JSON object, for CI. The exit code says what happened: 0 ok, 1 the checks failed, references wait or a person’s draft is in the way, 2 usage or configuration, 3 the key was refused, 4 not available, 5 the server or the network.

The CLI refuses to run when it finds an API key in the repository, and it never prints the key. Revoke a key that was ever committed: it stays in the repository’s history.

4. Give the agent the MCP server

acriva mcp serves the same checks to the agent over MCP (stdio): the tools validate, test_run and import_draft, and as resources the SDK’s declarations, an overview for script authors, the workspace’s types and the cookbook’s index. No tool publishes, pauses, resumes or deletes. For Claude Code:

export ACRIVA_API_KEY=acv_live_…
claude mcp add acriva -e ACRIVA_URL=https://app.acriva.de -e ACRIVA_TENANT=<workspace> -- npx @acriva/cli@<version> mcp

The server marks what it quotes from the repository, a run or the server as untrusted data for the agent. With --allow-real-documents, a test run may use a real document: its values then reach the agent’s model outside Acriva’s AI gateway and its controls, as your own processing, and they stay in the agent’s local transcripts. That session offers no import. Set it only in your own tool’s configuration.

5. The draft in the app

The pushed workflow is a draft in the workflow designer. The designer names its source above the canvas, Imported through API key “‹name›”, and the publish dialog names it under Source. Check the draft like any other: the canvas, the scripts, the problems, and a Test run on a document of the workspace. When the push replaced a draft that a person had saved, the designer says whose draft is kept, and Restore previous draft brings it back (A draft that an API key imported).

6. Publishing is a person’s click

Select Publish in the designer. The dialog shows the check and what the new version changes; only its confirmation makes the new version. Until then the published version keeps running, and no command or agent can publish it.

Writing and fixing scripts with AI in the editor

The script editor has AI of its own, through Acriva’s AI gateway: With AI writes a script from a description, Explain error (AI, 1 credit) and Fix error (AI, 1 credit) at a problem the check marks (Ctrl+.) explain and fix it, and suggestions while typing complete a line (switched off until you turn them on). Each proposal is a diff that changes only the draft; nothing is saved before you Accept it, and the server’s check runs on it as on any edit. What reaches the model is the script, the problem and the declarations, never a document or its values. A request costs credits; more in Write and fix with AI.

The agent in the repository and the editor’s AI are two ways to the same draft: both end before the publish, which only a person can do.