Skip to main content
skill CX Codex

corezoid-state-diagram-create — Claude Code skill: setup & overview

corezoid-state-diagram-create designs Corezoid state diagrams with conv_type: state, sets up entity lifecycles, and generates valid diagram JSON files.

MIT ★ 74 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid
Open on GitHub

What corezoid-state-diagram-create does

This skill acts as a specialist for Corezoid state diagrams using the corezoid MCP server. It starts by gathering entity parameters: stable ref identifiers, state names, outbound transition triggers, and initial or terminal steps. Once clarified, it triggers the create-state-diagram MCP tool to produce the <ID>_<Name>.conv.json skeleton, or imports existing objects with pull-process.

A Corezoid state diagram allows only 10 specific node types. Integration nodes like API Call, DB Call, Git Call, and process calls are forbidden inside state stores; they belong strictly in driver processes. Every state node gets built around an api_callback anchor, condition branches, and a self-referencing go fallback.

What it helps with

  • design entity lifecycle state machines inside Corezoid
  • generate conv_type: state schema JSON with correct 24-hex node IDs
  • configure state nodes with api_callback parking logic and transition routes
  • prevent forbidden integration nodes from entering state diagrams

Example prompts for the agent

  • Create a Corezoid state diagram to track user account lifecycles
  • Build a state machine for order statuses with Pending, Active, and Closed
  • Set up a state diagram keyed by orderId using the corezoid MCP tools

How to install corezoid-state-diagram-create

1Plugin marketplace

/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid

This installs the whole corezoid plugin with all its skills

2Skills CLI (Vercel)

npx skills add corezoid/corezoid-ai-plugin --skill corezoid-state-diagram-create -a claude-code

3Manually: put the files in place

~/.claude/skills/corezoid-state-diagram-create/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/corezoid-state-diagram-create/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about corezoid-state-diagram-create

How to install corezoid-state-diagram-create in Claude Code?

Run /plugin marketplace add corezoid/corezoid-ai-plugin followed by /plugin install corezoid@corezoid.

What does corezoid-state-diagram-create do?

It structures Corezoid state machines, asks for lifecycle constraints, and outputs compliant .conv.json files via the Corezoid MCP server.

Which node types are prohibited in Corezoid state diagrams?

Nodes such as API Call, DB Call, Git Call, Sum, API Form, and Call a Process cannot be used. External interactions must stay inside driver processes.

Source text

SKILL.md · MIT
---
name: corezoid-state-diagram-create
description: >
  Corezoid state diagram creation specialist. Use when the user wants to create
  a new Corezoid state diagram, build a state machine, design a status / lifecycle
  store, or set up a "state" object with conv_type "state". Activate when the
  user says "create a state diagram", "build a state machine", "new state diagram",
  "design states", "track status", "user lifecycle", "состояния", "стейт диаграмма",
  "создать state diagram", or mentions storing state-by-ref between processes.
---

# Create a New Corezoid State Diagram

You are a specialist in creating Corezoid **state diagrams** (`conv_type: "state"`) using the `corezoid` MCP server.

A state diagram is a long-lived data store: each task is one entity's state, referenced by a stable `ref`. Other processes read, create, and modify these state tasks. The state diagram itself only contains states (parked tasks), transitions between them, and a tiny subset of helper nodes.

Before you start, make sure you understand:
- A state diagram has `conv_type: "state"` at the root (not `"process"`).
- Only 10 node types are allowed: Start, Condition, Code, Set Parameters, Copy Task, Modify Task, Set State (= a state node), Delay, Queue, End: Success, End: Error.
- API Call, Call a Process, Reply to Process, DB Call, Git Call, Sum, API Form are **forbidden** inside a state diagram — they belong in the driver process.

Read `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-overview.md` if you need a refresher on the model.

---

## Step 1: Gather Requirements

Ask the user for the following before proceeding:

- **What entity is being tracked?** (user, order, device, subscription, account, …)
- **What is the `ref`?** — the stable identifier (e.g. `userId`, `orderId`). This is the lookup key every reader and writer will use.
- **List the states.** A name and a one-line description for each (e.g. `Pending`, `Active`, `Suspended`, `Closed`).
- **List the transitions.** For every state, what data change causes it to move to which other state? (e.g. `Active → Suspended when status == "suspended"`).
- **Initial state.** Which state does a newly created task enter first?
- **Terminal states.** Which states are "End: Success" / "End: Error", if any?
- **Side effects on entry / exit (optional).** Should entering a state trigger a notification, stamp a timestamp, etc.? (These are Copy Task / Modify Task nodes between states.)

If any of the above is missing, ask the user before continuing.

---

## Step 2: Create the Empty State Diagram

Call MCP tool **`create-state-diagram`** with:
- `folder_path`: Relative path to the folder directory. Omit to use the current directory.
- `process_name`: the state diagram name.

This creates an empty state diagram in Corezoid with `conv_type: "state"` and writes its skeleton JSON to `<ID>_<Name>.conv.json` inside `folder_path`. The returned file path is `PROCESS_PATH` — all subsequent steps use it.

> ⚠️ Always verify `folder_path` points to the intended target folder. Omitting it places the diagram in the project root, which may not be the correct location.

> ⚠️ Open the new file and confirm `"conv_type": "state"` at the root before doing anything else. The push pipeline now accepts both `"process"` and `"state"`, but if `conv_type` is accidentally `"process"`, the next push will redeploy it as a regular process.

**Already exists in Corezoid?** If the user pre-created the diagram in the Corezoid UI, pull it instead: call MCP tool **`pull-process`** with `process_id: <id>`. `pull-process` works for both processes and state diagrams — the resulting file preserves `conv_type: "state"`.

---

## Step 3: Design the State Diagram Structure

A state diagram is structured as:

| # | Node | obj_type | Purpose |
|---|------|----------|---------|
| 1 | Start | 1 | Entry — routes a newly-created task to its initial state |
| 2 | _(optional)_ Set Parameters / Code | 0 | Compute / normalise data on entry |
| 3 | One state node per state | 0 (logic begins with `api_callback`) | Park the task until externally modified |
| 4 | _(optional)_ Copy Task / Modify Task between states | 0 | Side effects on transition |
| 5 | _(optional)_ Delay node | 0 | Time-bounded states (e.g. trial expiry) |
| 6 | End: Success | 2 | Terminal state for "happy" closure |
| 7 | End: Error | 2 | Terminal state for failure closure |

### State node anatomy (memorise this shape)

```json
{
  "id": "<24-hex>",
  "obj_type": 0,
  "condition": {
    "logics": [
      { "type": "api_callback" },
      {
        "type": "go_if_const",
        "to_node_id": "<other_state_id>",
        "conditions": [
          { "param": "status", "const": "blocked", "fun": "eq", "cast": "string" }
        ]
      },
      { "type": "go", "to_node_id": "<self_id>" }
    ],
    "semaphors": []
  },
  "title": "Active",
  "x": 880, "y": 400,
  "extra": "{\"modeForm\":\"expand\",\"icon\":\"state\"}",
  "options": null
}
```

Key invariants for every state node:
- **First logic is `api_callback`** (with no other fields). This is what "parks" the task.
- One `go_if_const` per outbound transition. Order matters — first match wins.
- **Last logic is `go` pointing back to the node's own id** (the "stay here" fallback).
- `extra` must include `"icon":"state"` so the UI renders the state pill correctly.
- Do not add `err_node_id` — `api_callback` does not surface the regular error path.

---

## Step 4: Generate the State Diagram JSON

Produce a valid `.conv.json` file with the following root envelope:

```json
{
  "obj_type": 1,
  "obj_id": <id from step 2>,
  "parent_id": <folder_id>,
  "title": "<State Diagram Name>",
  "description": "",
  "status": "active",
  "params": [],
  "ref_mask": true,
  "conv_type": "state",
  "scheme": {
    "nodes": [],
    "web_settings": [[], []]
  }
}
```

### Core rules

- `conv_type` **must** be `"state"`.
- Node IDs are 24-character hex: `^[0-9a-f]{24}$`. Generate with `crypto.randomBytes(12).toString('hex')` or any equivalent.
- Connect nodes only through the `go` / `go_if_const` `to_node_id` fields.
- Every node that uses logic with `err_node_id` (Code, Set Parameters, Copy Task, Modify Task, Queue) must point at a dedicated End: Error node.
- Use descriptive node `title` values — they are the state names visible on the canvas and in dashboards.
- Layout: spread states **horizontally** (different `x` per state), keep the Start above them. State nodes sit around `y ≈ 400`, Start at `y = 100`. Increment `x` by ≈ 320–400 between adjacent states. Place End nodes at the bottom (`y ≈ 700–900`).

### Allowed logics inside a state diagram

| Node | Logic `type` | Notes |
|---|---|---|
| Start | `go` (`obj_type: 1`) | Exactly one per diagram |
| State (Set State) | `api_callback` + `go_if_const`s + self-`go` | The structural heart of the diagram |
| Condition | `go_if_const` | For pre-state routing |
| Code | `api_code` | Avoid unless necessary; prefer `set_param` |
| Set Parameters | `set_param` | Compute / stamp fields |
| Copy Task | `api_copy` with `mode: "create"` | Fan out to another process (notifications, audit) — **not** to write back to this same diagram |
| Modify Task | `api_copy` with `mode: "modify"` | Update a task by `ref` in some target process — note: in-place edits to the current task should use `set_param` instead |
| Delay | semaphor-only | Time-bounded states |
| Queue | `api_queue` | Ordered / throttled processing |
| End | (`obj_type: 2`) | Terminal node (success or error icon) |

### Variables for constants

If a node references an external id (e.g. another process to notify), store it as a Corezoid variable and reference it as `{{env_var[@variable-name]}}` — never hardcode. Use **`cz-variables`** with `action: "create-variable"` if the variable does not yet exist. See `${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md`.

### Common pitfalls

- Forgetting `"icon":"state"` in `extra` for a state node — the node renders as a plain logic node.
- Missing the trailing self-loop `go` on a state node — the task escapes the state on every callback.
- Putting an API Call, Call a Process, or Reply to Process node in a state diagram — these are **forbidden**. Move them into the driver process.
- Using `api_copy mode: "modify"` from inside the state diagram targeting its own ref — that creates an infinite re-callback loop. Use `set_param` to update the current task in place instead.
- Raw JSON objects as `extra` / `data` values — must be stringified (`"{\"k\":\"v\"}"`).

---

## Step 5: Validate with Lint

Call MCP tool **`lint-process`** with `process_path: "<PROCESS_PATH>"`.

Fix every reported error and re-run until the output is clean. Do not proceed with lint errors.

> If the linter complains about a forbidden logic (`api`, `api_rpc`, `api_rpc_reply`, `db_call`, `git_call`, `api_sum`, `api_form`), remove the node and re-design the side effect to live in the driver process.

---

## Step 6: Deploy

Call MCP tool **`push-process`** with `process_path: "<PROCESS_PATH>"`.

If the push fails:
- Re-read the file and confirm `"conv_type": "state"` is present at the root.
- Confirm every state node ends in `go → self`.
- Confirm only allowed logic types are present.

After a successful push, notify the user:

> "State diagram deployed. Refresh the Corezoid page to see the new diagram. To start using it, create the driver process that calls `api_copy mode:create` with a `ref` to add entities, and `mode:modify` to drive transitions."

---

## Step 7 (optional): Build the Driver Process

A state diagram is useless without a driver process that creates and modifies its tasks. If the user has not already built one, offer to:

1. Hand off to `/corezoid-create` to scaffold the driver process.
2. Wire it with three node patterns:
   - **Read state:** `set_param` with `{{conv[<sd_id>].ref[{{ref}}].<field>}}`
   - **Create state task:** `api_copy` with `conv_id: <sd_id>`, `ref: {{<ref>}}`, `mode: "create"`, `data: {...}`
   - **Modify state task:** `api_copy` with `conv_id: <sd_id>`, `ref: {{<ref>}}`, `mode: "modify"`, `data: {...}`

Read `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-process-interaction.md` for full templates.

Recommend creating an alias (`/corezoid-alias-manager`) for the state diagram so the driver references `@user-states` instead of a numeric id.

---

## Reference Documents

| Path | When to read |
|---|---|
| `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-overview.md` | Concepts, allowed nodes, root structure |
| `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-node-structures.md` | Canonical JSON for every allowed node type |
| `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-process-interaction.md` | How driver processes read / create / modify state tasks |
| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/set-state-node.md` | Background on Set State (legacy `obj_type:3` form) and the `{{conv[...]}}` template |
| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/copy-task-node.md` | Error catalogue for `api_copy` |
| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/condition-node.md` | `go_if_const` reference |
| `${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md` | Variables (`{{env_var[@…]}}`) |

## Example Files

| Path | Description |
|---|---|
| `${CLAUDE_PLUGIN_ROOT}/samples/state-diagrams/user-status-state-diagram.conv.json` | Minimal two-state diagram (`Active` ⇄ `Inactive`) |
| `${CLAUDE_PLUGIN_ROOT}/samples/state-diagrams/user-status-driver-process.conv.json` | Companion driver process that reads + modifies the state |

© Corezoid · MIT · corezoid/corezoid-ai-plugin

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →

From the same set30

The whole set →
corezoid-access corezoid-access — a skill for managing access to processes, folders and projects in Corezoid. Share objects with users and groups, create API keys, invite external users, and audit who has access. CX Codex +1 ★ 74repo stars corezoid-project-review corezoid-project-review audits entire Corezoid projects or folders, finding circular calls, duplicate code logic, and shared hardcoded secrets. CX Codex +1 ★ 74repo stars corezoid-init corezoid-init connects a working directory to Corezoid, handles sign-in, and pulls a selected stage. Use it when starting a Corezoid project. CX Codex +1 ★ 74repo stars release Walks through six release phases: compares your code to the last tag, suggests a version number, updates seven manifest files, and creates a git tag. CX Codex +1 ★ 74repo stars corezoid-process-optimizer corezoid-process-optimizer reviews Corezoid process JSON and proposes or applies changes such as merging nodes, cleaning data, and filling missing titles. CX Codex +1 ★ 74repo stars corezoid-connector-create corezoid-connector-create — a skill that generates a Corezoid process calling a single endpoint of any HTTP API (Stripe, OpenWeather, banks, CRM, or your own service). CX Codex +1 ★ 74repo stars corezoid-gitcall corezoid-gitcall configures isolated Git Call nodes in Corezoid processes to execute custom code in 9 languages or Docker when native nodes are insufficient. CX Codex +1 ★ 74repo stars corezoid-edit The corezoid-edit skill edits existing Corezoid processes through an MCP server, covering node changes, API calls, and logic fixes. CX Codex +1 ★ 74repo stars

Project sponsors

Companies that keep this analytics open