Skip to main content
skill CX Codex

corezoid-node-layout — Claude Code skill: install and use

corezoid-node-layout arranges Corezoid process nodes into a readable top-to-bottom flow and moves error handling to the right. Use it before pushing a new process or after a layout request.

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-node-layout does

This skill runs the layout-process MCP tool against a .conv.json file. It creates a vertical main flow, places branches around it, and removes node collisions. Small tree-shaped processes use a waterfall layout; larger graphs separate the business flow from local error groups and shared error handling on the right.

Run it after the nodes and edges are complete and before push-process, then use lint-process. The tool edits only x and y, leaving logic, edges, node types, conv_id, aliases, and extra.modeForm state intact. You can preview coordinates with dry=true and choose compact, medium, or roomy spacing; medium is the default.

It works on the local file without authentication or a network request because the engine is part of the plugin's Go MCP server. An existing user-authored process is preserved unless the user asks for a full rearrangement. When nodes are added to such a process, new nodes stay at x: 0, y: 0 until push-process places them near their graph neighbours.

What it helps with

  • arrange a Corezoid process as a vertical flow
  • remove overlaps between process nodes
  • move error handling into a right-side rail
  • keep the diagram readable before push-process

Example prompts for the agent

  • Arrange the nodes in process.conv.json and prepare the process for push-process.
  • Preview the planned layout for process.conv.json with dry=true without changing the file.
  • Rearrange process.conv.json with compact density, then run lint-process.

How to install corezoid-node-layout

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-node-layout -a claude-code

3Manually: put the files in place

~/.claude/skills/corezoid-node-layout/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/corezoid-node-layout/

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

Questions about corezoid-node-layout

How do I install corezoid-node-layout in Claude Code?

Add the marketplace with /plugin marketplace add corezoid/corezoid-ai-plugin, then install the plugin with /plugin install corezoid@corezoid.

What does corezoid-node-layout do?

It runs layout-process to place Corezoid nodes automatically. The main flow runs from top to bottom, error handling moves to the right, and only x and y coordinates are changed.

Can I run it on an existing process?

Yes, when the user explicitly asks for a rearrangement. Otherwise the existing coordinates stay intact, while newly added nodes remain at x: 0, y: 0 until push-process.

Source text

SKILL.md · MIT
---
name: corezoid-node-layout
description: >
  Auto-arrange the nodes of a Corezoid process into a clean, readable layout —
  a vertical top-to-bottom business flow with error handling railed off to the
  right and no overlapping nodes. Use it AUTOMATICALLY on every process YOU
  built or assembled, as the last step before push-process — never hand-place
  coordinates by eye (eyeballed grids overlap the moment nodes are taller than
  the step). Also reach for it whenever the user says a process is unreadable,
  tangled, ugly, a mess, or that nodes sit on top of each other, or asks to
  "arrange", "lay out", "tidy up", "make readable", "fix positions", "clean
  the diagram", "remove the overlaps" — or their equivalents in any language
  the user speaks. Do NOT silently
  re-arrange a process the user already positioned — see the "When you MAY
  re-layout" rules in the body. It changes x/y coordinates only — never
  collapse/expand state, edges, logic, conv_id, aliases or node types.
---

# Auto-Layout Corezoid Process Nodes

You make a process **readable**: business logic as a clear vertical spine,
error handling collected in a tidy right-hand rail, nothing overlapping. This is
the mechanical companion to the positioning rules in
`${CLAUDE_PLUGIN_ROOT}/docs/process/node-positioning-best-practices.md` — that
doc is the source of truth for *why*; this skill *does it* deterministically.

## When you MAY re-layout — and when you MUST NOT

A process's layout is part of how its author reads it. Re-flowing someone's
diagram without asking is destructive even though the logic is untouched — it
throws away a mental map they are used to. So the rule is about **authorship**,
not just readability:

- **A process YOU built this session, from scratch → always lay it out.** You
  own its positions; arrange it cleanly before `push-process`. No need to ask.

- **An existing / pulled / user-authored process → do NOT re-layout by
  default.** Preserve the author's `x`/`y`. This holds even if you just edited
  it — a user who is used to their arrangement must not find it rearranged.

- **When you add nodes to someone else's process** (an edit, not a rebuild):
  leave the new nodes at `x: 0, y: 0` — `push-process` auto-places them next
  to their graph neighbours while keeping every existing node where it was
  (preserve mode; see node-positioning-best-practices.md § Automatic
  Placement on Push). Do **not** run the whole-process auto-layout — that
  repositions everything. Full re-layout on a foreign process happens only on
  request.

- **The user explicitly asks** ("tidy this up", "fix the positions", "make it
  readable" — in any language) → re-layout the whole process. This is the one
  case where rearranging a foreign process is wanted.

- **The process is genuinely unreadable** (heavy node overlaps, a tangled mess)
  → don't silently fix it. **Offer**: briefly say it's hard to read and ask if
  they want it re-arranged. Re-layout only after a clear yes. If they decline,
  leave it exactly as is.

When in doubt, ask before touching an existing layout — a wrong guess costs the
user their familiarity; asking costs one sentence.

## Workflow (once the rules above say you may)

Run the layout **after** the process JSON is finalized and **before**
`push-process`:

1. finish building the process (nodes + edges correct),
2. call the **`layout-process`** MCP tool on the `.conv.json`,
3. `lint-process`, then `push-process`.

The tool rewrites the file in place, touching only `x`/`y`. The user's existing
`extra.modeForm` state is immutable: expanded nodes stay expanded and collapsed
nodes stay collapsed. `extra`, edges, logic, `conv_id`, aliases and node types
are left intact.

## How to run

Call the MCP tool (no auth needed — it works entirely on the local file):

```
layout-process(process_path="path/to/NNN_name.conv.json")
```

Preview without writing (the result lists the planned coordinates):

```
layout-process(process_path="path/to/NNN_name.conv.json", dry=true)
```

Control the spacing with `density="compact"|"medium"|"roomy"` (default
`medium`). The density pass re-spaces rows and columns from the nodes' REAL
sizes — a row of collapsed 48px IF-squares stops reserving a full block-row
of air, so a process fits on screen without zooming out. `roomy` skips the
pass and keeps the coarse block-sized rhythm (useful for presentations).

The same tool is available from a shell via the server's CLI mode:

```bash
sh "${CLAUDE_PLUGIN_ROOT}/mcp-server/run.sh" layout-process process_path=<file> dry=true
```

The engine lives inside the plugin's Go MCP server — no extra runtime, no
network, no server call.

## What it does (the layout rules it enforces)

The engine picks a strategy automatically (the result reports which one and why):

- **Small and tree-like processes** (fewer than ~25 nodes, or one main flow
  with branches) → a vertical "waterfall": the happy path runs straight down
  the central column, branches fan out to the sides (longer branches nearer
  the centre — a hub with rays reads as a star, cascaded IFs as a tree), and
  each error cluster is pinned tight to the right of the node it protects.
  Small processes always get the waterfall: the layered machinery below only
  pays off at scale, and on a small graph its spine drifts sideways.

- **Region composition** — big processes routinely combine shapes, so region
  detection runs in a loop and each region gets its own geometry while the
  rest of the graph keeps the waterfall:
  - **TABLE**: a dispatcher fanning into 3+ structurally identical pipelines
    that reconverge (one sync pipeline per entity type is the canonical case)
    → parallel columns with row-aligned steps, and the shared tail (a DLQ,
    the columns' error clusters) in a side column;
  - **STAR / sun**: a hub fanning into 4+ chain-shaped rays of *varying*
    depth that reconverge → rays hang symmetrically around the hub→merge
    axis, deepest nearest the axis (a fir-tree silhouette);
  - **DIAMOND**: a compact two-way fork/rejoin → the primary branch stays on
    the hub axis, the short optional branch sits immediately to its right,
    and the merge returns to the original axis;
  - several regions in sequence — two tables, a star followed by a table —
    compose cleanly (each expansion makes its own room).

- **Large mesh processes** (many independent flows, lots of error handling)
  → the graph is split into (1) the **business flow**, laid out as a clean
  layered top-to-bottom spine with edge-crossings minimised, (2) **dedicated
  error clusters**, pinned locally beside their single owner, (3) genuinely
  **shared error clusters**, placed on a clean right rail using their existing
  collapse/expand state, and (4)
  unreachable historical components, packed into a separate zone below the
  active Start flow. A high error-node percentage alone does not select this
  strategy; ownership topology does.

- **Recovery lanes** — an `err_node_id` target is not automatically terminal
  error handling. If it enters a substantial compensating pipeline or rejoins
  the active flow, that pipeline is anchored beside its owner/merge as business
  logic while retaining its current mode. Callback entrypoints are treated like Start
  roots; a component goes to the archive zone only when it has no attachment
  to the active graph in either direction.

Both strategies guarantee: **no node overlaps**, top-to-bottom flow with
Start at the top and the deepest success Final sunk to the bottom of the active
flow (early success exits remain local), every node's existing collapse/expand
state preserved, and the diagram re-centred on the origin so it sits in the
middle of the canvas instead of drifting off one edge.

Note what that last point is *not*: there is no hard ±10000 clamp. The vertical
step does shrink for deep processes, but it has a floor, so a very deep process
(roughly 125+ layers) legitimately extends past ±10000. That is fine — the node
schema allows ±100000 precisely because real processes reach about ±25500.

**Example** — a typical result on a freshly built process:

```
strategy: waterfall  (21 nodes, 4 flow(s), 5% error-handling nodes)  density=medium  engine=recovery-v6-preserve-modes
nodes=21 width=1000px height=4070px overlaps=0 collapsed=0
readability: estimated-crossings=0 max-dedicated-error-span=376px long-dedicated-errors=0
edges: max-span=420px p95-span=310px long=0 upward=0
layout applied: 042_payment.conv.json (21 nodes, 21 moved)
Next: lint-process, then push-process.
```

`overlaps=0` is the number to check; anything else means a bug worth reporting.
Full re-layout is idempotent: running it again over its own output must preserve
the same coordinates. Every input `extra.modeForm` must be identical after the
run; `collapsed=0` and `mode-passes=1` are mandatory. The engine revision makes
stale runtime tests visible.

## Honest limits

Some graphs cannot be made beautiful because the *graph itself* is tangled — a
node called from a dozen places is an unavoidable fan of edges no layout can
remove. When a process is this big and knotty, the real fix is to **split it
into smaller, repeatable sub-processes**; the layout only makes an unavoidable
monster as readable as it can be, never magically simple.

## Verifying a change to the engine

The engine's test suite lives with the server code
(`plugins/corezoid/mcp-server/layout_*_test.go` — synthetic topologies:
chains, stars, loops, fractals, tables, and an error-heavy process):

```bash
cd "${CLAUDE_PLUGIN_ROOT}/mcp-server" && go test -run 'TestLayout' ./...
```

It asserts the invariants that make a layout clean: all nodes placed, **zero
overlaps**, deterministic output (so adding a node re-flows rather than piles
up), coordinates within canvas, top-to-bottom flow, correct strategy routing,
table/star/diamond region geometry, dedicated-vs-shared error ownership,
detached component zoning, local early exits, and golden coordinate files that
freeze every fixture against unintended churn.

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

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →
node-link-and-diagram-layout official OpenAI The node-link-and-diagram-layout skill selects layouts for graphs, diagrams, and connected nodes. Use it when crossings, overlaps, edge routing, or unstable placement make a visual hard to read. CX Codex GP ChatGPT +1 16installs n8n-node-configuration-official n8n-io n8n-node-configuration-official keeps your agent from guessing n8n node parameters. It fetches the live shape first, so validation errors stop eating your build time. CX Codex +1 2,300installs n8n-node-configuration czlonkowski n8n-node-configuration guides agents through n8n node setup, operation-specific fields, and parameter dependencies. Useful when building or validating workflows. CX Codex +1 8,100installs node-deps-bumper PaulRBerg node-deps-bumper — a skill for Claude Code and Codex that structures package upgrades via Taze and guards against regressions. Runs whenever npm, pnpm, yarn, or bun dependencies need updates or dry-run checks. CX Codex +1 106installs flutter-fix-layout-issues flutter flutter-fix-layout-issues reads a Flutter layout exception and tells you what to wrap in what: overflow stripes, unbounded constraints, misplaced ParentData widgets. CX Codex +1 43,700installs iphone-duo-adaptive-layout mirzaaghazadeh iphone-duo-adaptive-layout is a Claude Code skill that teaches agents to build layouts around the iPhone Duo fold with reserved regions, displacement, split, and overlay containers for avoiding the hinge and camera. CX Codex +1 1,000installs

From the same set30

The whole set →
corezoid-dashboard-manager corezoid-dashboard-manager is a Claude Code skill that builds Corezoid dashboards via cz-dashboards, mapping process node task counters to charts and setting grid layouts. CX Codex +1 ★ 74repo stars corezoid-git-context The corezoid-git-context skill records meaningful Corezoid session changes in stage documentation and syncs the git mirror. Use it after real process work. CX Codex +1 ★ 74repo stars plan-to-issues plan-to-issues converts a plan discussed in the chat into structured GitHub issues: an epic plus child tasks grouped by milestone and labeled by type. Triggers on command or keywords like "split plan into tasks" or "make issues from this". CX Codex +1 ★ 74repo stars corezoid-state-diagram-edit corezoid-state-diagram-edit — a skill for updating Corezoid state diagrams in .conv.json files. Adjusts states, transition paths, and transition side effects. CX Codex +1 ★ 74repo stars 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

Project sponsors

Companies that keep this analytics open