---
title: Build with a coding agent and a build kit
editUrl: https://github.com/Cratis/cli/edit/main/Documentation/builders/agents-and-kits.md
description: Run a Cratis Studio builder with Claude Code, Codex, Gemini CLI, Copilot CLI, OpenCode or any ACP agent, and describe a stack with a build kit.
lastUpdated: 2026-11-15T00:00:00.000Z
---


A builder can hand each build order to a coding agent instead of a [generator](/cli/builders/write-a-generator/). The CLI still does the rest: it talks to Studio, verifies, commits, pushes and reports. A build kit describes the stack the builder builds, for agents and generators alike. The [`cratis build` reference](/cli/reference/build/) has every option.

This page is the reference for agents and kits. For a complete, working kit to start from, see [Build with AI](/cli/builders/build-with-ai/), where the agent writes the code, and [Deterministic with AI on top](/cli/builders/deterministic-and-ai/), where a generator in the kit writes the structure and the agent completes it.

## Choose an agent

```bash
cratis build run --agent claude --verify "dotnet test"
```

| `--agent` | Agent | How it runs |
| --- | --- | --- |
| `claude` | Claude Code | Through its own command line. |
| `codex` | Codex | Over the Agent Client Protocol, through `npx -y @zed-industries/codex-acp`. |
| `gemini` | Gemini CLI | Over the Agent Client Protocol, through `gemini --experimental-acp`. |
| `copilot` | GitHub Copilot CLI | Over the Agent Client Protocol, through `copilot --acp`. |
| `opencode` | OpenCode | Over the Agent Client Protocol, through `opencode acp`. |
| `cursor`, `acp` | Any ACP agent | Over the Agent Client Protocol, through the command you give with `--agent-command`. |

`--agent-command` overrides the command for any agent. The agent runs with its own sign-in. `cratis build init --agent <agent>` records the agent in the project, so `run` and `once` use it without `--agent`.

## What an agent gets

- **A prompt** filled from the order, telling it which slices to build and where to write its outcome. The order itself is in a folder outside the project.
- **The Screenplay session guidance**, the version Studio pins, unless you add `--no-guidance`.
- **The kit's instructions and skills**, when the project has a kit.
- **Tools**: Screenplay's tools on the order's model, and Studio's board tools when the organization's MCP credential is configured.

The agent writes the same [outcome](/cli/builders/write-a-generator/#the-outcome) a generator does. If it stops without one, the CLI asks it to go on, up to twice.

An agent is never run with its permission checks switched off. It may read the project and the folders handed to it, write only the paths the kit permits, and run only the commands the kit permits and the verification commands. Web fetches are refused. No credential is written into a prompt, a file the agent reads, an outcome or the log.

### Give agents Studio's tools

```bash
export CRATIS_STUDIO_MCP_SECRET=...   # the organization's MCP client secret
cratis build connect --studio --organization acme --mcp-client-id <client id>
```

The client id and secret come from **Organization settings › MCP** in Studio. The secret is read from `CRATIS_STUDIO_MCP_SECRET`, or asked for in the terminal; it is never taken on the command line. The same credential lets `cratis studio fetch` export the context of a slice, feature, event model or domain.

## Build kits

Without a kit, a builder builds the backend of every slice type, may write anywhere in the project, and verifies with `--verify` only. A kit narrows and describes that:

| A kit says | So that |
| --- | --- |
| `sliceTypes` | Studio offers the builder only those slice types. |
| `ui: true` | Studio offers user interface orders too, not only backend ones. |
| `verify` | Every build runs these commands before committing. |
| `permissions` | The paths agents may write and the CLI commits, and the commands agents may run. |
| `git` | The branch and commit message when Studio does not name them. |
| `instructions`, `skills`, `prompt` | What an agent is told. |
| `scaffold`, `requires`, `existingCodebase` | How `init` sets up a new or existing project. |

### Install a kit

```bash
cratis build init --kit cratis-csharp --agent claude
```

`--kit` is a kit Studio registers by name (`cratis-csharp`, `node`), a Git URL (end it with `#<branch, tag or commit>` to pin it), or a folder. `init` validates the kit, checks the commands it requires, scaffolds an empty project, copies the kit to `.cratis/build/kit` and installs its instructions and skills where the agent reads them. It records what it did in `.cratis/build/kit.json`; `run`, `once` and `service install` read the kit from there. `--kit <path>` on `run` or `once` uses another kit for one run.

### Write a kit

A kit is a folder with a `build-kit.yaml` (or `build-kit.json`) manifest and the files it names:

```yaml title="build-kit.yaml"
kitVersion: "1"
name: slice-sheets
version: 1.0.0
description: Writes a Markdown sheet for each slice.
sliceTypes: [stateChange, stateView, automation, translation]
ui: false
instructions: ./AGENTS.md
prompt: ./build-slice.md
verify:
  - test -f slices/{feature}/{slice}.md
git:
  branch: "build/{feature}"
  commit: "Build {slices} ({part})"
permissions:
  paths: ["slices/**"]
  commands: [ls]
```

`kitVersion`, `name`, `version`, `description`, `sliceTypes`, `instructions`, `prompt` and `verify` are required. Paths inside the kit start with `./`. Commands, prompts, branch names and commit messages may use these placeholders: `{order}`, `{outcome}`, `{slice}`, `{slices}`, `{sliceId}`, `{feature}`, `{featurePath}`, `{application}`, `{part}`, `{attempt}` and `{conventions}`. `{slice}` and `{sliceId}` are the order's first slice; `{slices}` names them all. In a command, each value is quoted for the shell, so do not quote placeholders yourself.

Check a kit the way Studio and the builder do:

```bash
cratis build kit validate ./slice-sheets-kit
```

It reports each problem with a JSON pointer into the manifest. The Studio documentation describes [the kit format](https://docs.cratis.studio/developers/builders/configure/cratis-build/) in full.

## Related

- [Connect and run a builder](/cli/builders/connect-and-run/)
- [Build with AI](/cli/builders/build-with-ai/)
- [Deterministic with AI on top](/cli/builders/deterministic-and-ai/)
- [Write a generator](/cli/builders/write-a-generator/)
- [`cratis build` reference](/cli/reference/build/)
