Skip to main content
skill CX Codex

scenario-zbrush-automation — Claude Code skill

scenario-zbrush-automation is a Claude Code skill for batch processing in ZBrush 2026: it imports OBJ and ZTL, runs scripts, exports SubTools, and handles GoZ with Maya and Blender.

MIT 430 installs ★ 3,964 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add scenario-labs/skills --skill scenario-zbrush-automation -a claude-code
Open on GitHub

What scenario-zbrush-automation does

The skill builds batch processes through isolated calls: each file is its own task, each step has a timeout, outputs are read back from disk. This isolates hung plugins from crashing the entire batch. It works with ZTL and OBJ formats, records palette macros, launches Python and ZScript via zb_launch, handles UV Master, Decimation Master and Multi Map Exporter, exports individual SubTools, manages GoZ exchanges with external apps, and renames SubTools.

Inside: a runner with checkpoints, Activity Watch to extract paths from ZBrush logs, dialog detection via has_next_filename(), Python environment isolation through remote_call that restores sys.path and sys.modules after every call. Requires scenario-zbrush-expert skill loaded first (bridge, launch, ops, audit, 2026 traps). Solves plugin press hangs, dialogs blocking batches, single files crashing the run, and GoZ updating the wrong SubTool.

Start by defining input scope: file count, format, faces per file, target app (Maya, Blender). Timeouts and DynaMesh settings tune to this automatically. Saves before ProjectAll are mandatory—that operation can crash the session.

What it helps with

  • process a folder of OBJ or ZTL files in one ZBrush session
  • run a ZScript or Python script with a timeout, restarting if it hangs
  • export each SubTool without dialogs that stop unattended scripts
  • set up GoZ round trips between ZBrush and Maya or Blender with name validation
  • batch-rename SubTools and generate a per-file results report

Example prompts for the agent

  • Process the models/ folder of OBJ files: import, DynaMesh to 1 million faces, export low-poly to output/
  • Run retopo.py on each ZTL in the project, capture errors and save a report
  • Send all SubTools from the current tool to Maya via GoZ, running Decimation Master first

How to install scenario-zbrush-automation

1Skills CLI (Vercel)

npx skills add scenario-labs/skills --skill scenario-zbrush-automation -a claude-code

2Manually: put the files in place

~/.claude/skills/scenario-zbrush-automation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/scenario-zbrush-automation/

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

Questions about scenario-zbrush-automation

How do I install scenario-zbrush-automation in Claude Code?

Run npx skills add scenario-labs/skills --skill scenario-zbrush-automation -a claude-code, then open ~/.claude/skills/scenario-zbrush-automation/SKILL.md. For Cursor use -a cursor; for GitHub Copilot use gh skill install scenario-labs/skills scenario-zbrush-automation.

What does scenario-zbrush-automation do?

It automates repeating ZBrush tasks: batch import and export, running scripts, app-to-app exchanges. The key benefit is resilience—if a plugin hangs, the batch moves to the next file instead of crashing the whole run.

Is scenario-zbrush-expert required?

Yes. It provides the ZBrush bridge, launch, ops, and validation that scenario-zbrush-automation builds on. Load it with skill_get (Scenario MCP) or ask to install from the repository.

Source text

SKILL.md · MIT
---
name: scenario-zbrush-automation
description: "Use when automating ZBrush 2026: batch processing a folder of OBJ or ZTL files, a ZBrush Python script or ZScript, recording a macro to learn a palette path, the ZBrush -script command line, scripting UV Master, Decimation Master or Multi Map Exporter, exporting every SubTool, GoZ or GoB round trips with Maya or Blender, renaming SubTools, or batch reports. Also when a plugin press never returns, a dialog stalls a batch, one file kills the whole run, or GoZ updates the wrong SubTool."
license: MIT
---

# ZBrush automation (tools and pipeline TD)

An expert ZBrush TD automates with contracts and proof: every file is its own tool, every step is a
separate call with a time limit, every output is read back from disk, and a hung plugin costs one
file, never the batch. ZBrush has no timeout, no undo control from Python and dialogs that code
cannot answer, so the safety lives on the agent side: the runner, the checkpoints, the report. If a
sibling skill named here is missing from your available skills, load it with `skill_get` (Scenario
MCP) or ask the user to install it (https://github.com/scenario-labs/skills#install); unattended,
proceed from tool schemas and flag the gap.

**REQUIRED BACKGROUND:** scenario-zbrush-expert (bridge, zb_launch, zb_ops, zb_audit, review loop,
2026 traps).

**Status (2026-09-24, refactor pass 2):** every ZBrush call here is **not yet run in ZBrush** (no
session assigned; the README's startup stall is still open). Offline: 56 tests pass
(`tests/code/zbrush-automation/run_offline.py`), including a GoZ reader and writer matching ZBrush's
own `ZResources/DXFStar.GoZ` byte for byte. Live suite: `tests/code/zbrush-automation/run_live.sh`.

## Stance (the expert delta)

- **One file, one tool, one step per call.** "Only one zscript/plugin can be active at a time, so if
  your zscript calls someting like UV Mapper control passes to UV Mapper and no more commands will
  run" (marcus_civis, ZBrushCentral 2014); pressing Decimation Master's Pre-process ended ijacobs'
  script (2013) and forced cgside into a two-run helper (2022, [00:06:56]). So the batch is an
  agent-side loop (`zb_batch.run_folder`) that sends each step as its own bridge call with its own
  timeout, pings after a timeout, and restarts ZBrush after a hang. One long in-ZBrush script dies
  with its first stuck plugin. [added design]
- **Plugins last, checkpoint first.** cgside saves before ProjectAll "since it might crash the
  program" [00:02:19]. `zb_ops.project_all` refuses to run without a versioned save and the recipe's
  project step passes one (`{stem}_preproject.ztl`), even with `save_ztl` off. Decimation Master
  runs last, after every valuable output is on disk, so a hang there leaves a `partial` file, not a
  lost one. [added]
- **Leave the interpreter as found.** ZBrush has one Python for the session and the script folder is
  not on `sys.path` (Maxon Style Guide). Send code only through `remote_call`/`zb_launch.run`:
  modules are imported by path, then `sys.path`, `sys.modules`, stdout and the working directory are
  restored, also after an error. End a batch with `zb_launch.hygiene()` (empty lists).
- **Dialogs are the automation killer; budget them before running.** A studio dropped ZBrush from
  its farm over Note dialogs (danvas 2017); "no way to detect whether they succeed or error"
  (BigRoyNL 2024); "if the export plugin, trigger a popup you are screwed" (m_adam, Maxon 2025).
  `set_next_filename` feeds built-in buttons only: FBX ExportImport shows options "You cannot
  escape" (ferdinand, Maxon 2025) and USD Format ignores the preset (usd-portal). Unattended exports
  are OBJ or `.GoZ` by path; `has_next_filename()` still true after a press means a dialog is
  probably waiting [added].
- **Names are identity.** GoZ needs unique names "including between all the loaded Tools" (GoZ
  docs); Decimation Master caches and UV Master control maps are keyed by the tool name, so a new
  tool with an old name inherits stale data (plugin docs). Stage each input under a unique,
  sanitized name before import (`stage_input`); on this Mac's case-insensitive disk `rock.obj` and
  `Rock.OBJ` are one file [added].
- **Learn paths from ZBrush, never guess.** Recordings show exact paths and hidden preconditions
  (Maxon ZScript manual; MadPony DnLlDJxfxHs [00:02:16]); Ctrl+hover shows a path. For an agent the
  cheapest oracle is ZBrush's own Activity log, which writes every press and set with its canonical
  path (`zb_batch.ActivityWatch`; proven by the 05:20 log). Then `zb_plugin_ops.probe()` confirms
  `exists`, range and title.
- **Record once, apply to all.** Pavlovich replays one recording on every visible SubTool with
  ZRepeat It [00:37:30]; ZRepeat It is not shipped in 2026.2.1, the Python equivalent is
  `for_each_subtool`.
- **Files, not live links, between apps.** GoZ sends the lowest subdivision level (GoZ docs;
  FlippedNormals [00:04:02]), updates by name, and raises a reprojection prompt when topology
  changed. An agent hands over `.GoZ` or OBJ files plus a manifest and lets the other app's agent
  import them.

## Establish first

| Input                                                 | Changes                                        | Default when silent                                                                                                                                                      |
| ----------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Inputs: count, format, faces per file                 | timeouts, DynaMesh resolution, restart cadence | OBJ, audited first with zb_audit                                                                                                                                         |
| Outputs: low count, map size and space, preview count | recipe params                                  | brief's numbers; else `DEFAULT_PARAMS` [added]                                                                                                                           |
| Parts per file, meaningful polygroups                 | ZRemesher grouping                             | cgside: Auto Groups then ZRemesher Keep Groups on the copy, so the low follows the parts (MyhwQvkcnwI [00:08:38]); `zr_auto_groups=False` when the input's groups matter |
| Target app: Maya, Blender, Unreal, Unity              | flip V, green channel, axes, format            | Maya: OBJ + tangent PNG flipped V, OpenGL green [added]                                                                                                                  |
| Whose ZBrush                                          | restart rights                                 | a ZBrush the batch did not start is never restarted or quit                                                                                                              |
| Watched or unattended                                 | pilot size, screenshot use                     | pilot of one file, watched                                                                                                                                               |
| Shared config allowed (GoZ folder, Macro palette)     | GoZ push, key-answer macros                    | no: ask first                                                                                                                                                            |

## Workflow

1. **Session and probe.** `zb_launch.start()` or reuse a running bridge; `zb_plugin_ops.probe()` on
   every path the recipe uses; `memory()`. GATE: ping returns 2026.2, every recipe path exists,
   plugins present.
2. **Plan dry.** `zb_batch.plan(files, out, params)` resolves every file's steps, paths and timeouts
   without ZBrush. GATE: outputs outside the install (read-only since 2026.1), unique stems, no FBX
   or USD step.
3. **Pilot one file, watched.** `run_folder([f], out, params)`; open `sheet.png` and the normal map;
   import the low and map in the target app (scenario-maya-pipeline-scripting or a Blender skill).
   GATE: file `ok`, step timings recorded, map orientation confirmed in the target app (flip V and
   green are [verify] until then).
4. **Run the batch.** Bridge mode by default; `mode="script"` (one `ZBrush -script` process per
   file) once live_a05 has shown how ZBrush exits. Drop a `STOP` file in the output folder to end
   between files; rerun to resume (sha1 and recipe hash). GATE: `report.json` written after every
   file.
5. **Recover.** For each `failed` or `partial`: read `steps[].outcome` (`error`,
   `timeout_recovered`, `hang`), the hang evidence (screenshot when the screen is unlocked; ZBrush
   Notes are drawn in the canvas, only the screenshot shows them), and `batch.blocked`. Fix params
   or paths, rerun: finished files are skipped. GATE: every non-ok file has a cause in the report.
6. **Review and deliver.** Open the contact sheet; check `low_audit`, `preview_audit`,
   `normal_stats`; write the handoff manifest. GATE: numbers pass, sheet looked at, report and
   manifest delivered.

## Numbers

| Value                                                                                              | Relative to                                                                 | Source                                        |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------- |
| UV Master: 100k to 150k faces max; seconds at 3k, up to 5 min at 150k                              | faces of the SubTool unwrapped                                              | UV Master doc                                 |
| Divide multiplies faces by 4; levels = smallest n with low x 4^n >= source faces, top capped at 8M | projection stack                                                            | Pablo Logic Part 7; cap [added]               |
| Decimation `% of decimation` is kept percent of points; 100 none, 0.01 max                         | points; about 2 triangles per point, so % = 100 x target_faces / 2 / points | DM doc; ijacobs 2013; Euler [added]           |
| DM quality: 40 to 100 % looks the same, 2 % still good, 1 % degrades                               | original model                                                              | DM doc                                        |
| ZRemesher target in thousands, approximate (5 gave 4,963)                                          | target polygons                                                             | Pablo Logic Part 7                            |
| Project All Dist 0.1, set explicitly                                                               | same shape, new topology                                                    | Drust nxMYYsyJt3o [00:02:19]; toolkit default |
| `create_normal_map(..., local_coordinates=True)` = tangent; default False = world                  | map space                                                                   | SDK stub                                      |
| Macro file name 8+ characters, in a subfolder; new folder needs a restart                          | `<Asset Dir>/ZStartup/Macros/`                                              | Maxon interfaces doc                          |
| Step timeouts 30 to 1,800 s, raised to 4 x slowest observed, 10 x base max; restart every 10 files | per step, per session                                                       | [added]                                       |
| Tangent map sanity: blue >= 128 on 90 % of pixels                                                  | final PNG                                                                   | [added]                                       |
| Maya GoZ flips Y and Z both ways and flips normal maps vertically                                  | GoZ_Info.txt                                                                | local file 2026-09-24                         |
| Blender FBX import from ZBrush: scale 1000                                                         | FBX                                                                         | FlippedNormals [00:11:21]                     |

## Quality gates

- **Per step (code):** import counts equal the file's (`import_mesh` warnings); DynaMesh `remeshed`;
  ZRemesher ratio to target 0.5 to 1.5 [added]; UV bbox inside 0..1; Divide ratio 4 per level; every
  output file exists and is non-empty. Each zb_ops `gate` (volume from `get_polymesh3d_volume`,
  watertight from `is_polymesh3d_solid`, projection spikes) feeds `check_step`: a collapsed or
  exploded DynaMesh or a spike fails the file.
- **Per file (code):** low OBJ passes `zb_audit.verdict(..., "game")` (UVs, no n-gons); low bbox
  equals the input bbox within 2 % (an OBJ import sets Export Scale: Outgang [00:24:03]) [added
  tolerance]; normal map at the asked size, not uniform, tangent-like; preview faces near target.
- **Per batch:** `counts`, `restarts`, `blocked`, `aborted` in `report.json`; `report.csv` for
  humans.
- **Visual:** `sheet.png` (one canvas snapshot per file, MatCap Gray): melted thin parts from a low
  DynaMesh, projection spikes, missing parts. The normal map applied in the target app, lit from the
  side: seams, upside-down or inverted detail.

## Common mistakes

| Mistake                           | What it looks like                                    | Fix                                                                       |
| --------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| One in-ZBrush loop over all files | first stuck plugin freezes everything, no report      | `run_folder`: one call per step, report per file                          |
| Pressing a plugin with no timeout | bridge silent for minutes                             | plugin steps are separate calls; `wait_recovery`, then restart            |
| Importing onto the active tool    | the active SubTool is replaced                        | `import_mesh`: PolyMesh3D star first (usd-portal)                         |
| Same-named inputs or tools        | stale Decimation cache, GoZ updates the wrong SubTool | `unique_stems` + `stage_input`                                            |
| FBX or USD in an unattended run   | options window, batch stuck                           | OBJ or `.GoZ` by path                                                     |
| Decimating the master             | sculpt gone, no undo from Python                      | checkpoint ZTL, decimate last or on a duplicate                           |
| Normal map from two SubTools      | no detail in the map                                  | the map compares levels of one SubTool (AskZBrush n0qqpwvn-jA [00:01:14]) |
| World-space map by default        | rainbow-colored map, wrong shading in engines         | `local_coordinates=True`                                                  |
| Restarting the user's ZBrush      | unsaved work lost                                     | `BridgeSession.owned`; abort instead                                      |
| Trusting `set()`                  | slider unchanged, no error                            | `exists()` then read back (zb_ops.set_checked)                            |

## Handoffs

- **Serves every persona:** batch versions of their procedures (`for_each_subtool`, recipes built
  with `zb_batch.step`), inventories before GoZ or export, path discovery. Receives their procedure
  and params; delivers `report.json`, `report.csv`, `sheet.png` and per-file outputs.
- **From scenario-maya-pipeline-scripting or a Blender skill:** OBJ or `.GoZ` files plus a manifest
  (names, units, which SubTool each updates). Names are checked with `zb_goz.check_names` before
  import.
- **To scenario-maya-pipeline-scripting, scenario-zbrush-retopology-export,
  scenario-blender-uv-baking:** low OBJ with UVs, tangent normal PNG (flip V and green stated),
  decimated preview, audit numbers, Export Scale and axis notes.
- **To a human or computer-use agent:** anything behind a dialog (FBX options, SubTool Rename and
  New Folder prompts, End Macro save dialog, GoZ app chooser, reprojection prompt).

## ZBrush 2026 notes

- Python (2026.0) runs next to ZScript; `press_key` "Does not work" and `merge_undo` is "Not
  implemented" (2026.1 stub): key-held presses and one-undo sequences need a ZScript macro pressed
  from Python [verify].
- Long deterministic sequences: `freeze(fn)` and `show_actions(0)` (SDK GUI reference) through
  `zb_ops.sequence`, `frozen`, `quiet`, or `for_each_subtool(..., freeze=True)`; never around a
  plugin press or a canvas export [added].
- Since 2026.1 the install is read-only: macros, plugins and `Python/init.py` go in the Asset
  Directory, here `~/Library/Preferences/Maxon/ZBrush_03C27D49/`.
- ZRepeat It, Turntabler and ZFileUtils are not shipped in 2026.2.1 (listing); no rename API exists
  (Maxon forum 2026-09).
- GoZ still reports "version 1.01 - April, 11th 2011"; Maya's GoZ config on this Mac points at a
  Maya 2017 that is not installed (`zb_goz.app_info`).
- Relaunches stalled after a `kill -9` at 05:29 (README, cause unknown): a restart after a hang may
  stall too. The runner then aborts with a resumable report.

## References

- [`references/procedures.md`](references/procedures.md): full code for each procedure (session,
  probe, import, per-file recipe, folder batch, `-script`, plugins, maps, SubTool loops, names, GoZ,
  Maya and Blender round trips, macros, file-drop, reports, interpreter hygiene). Load before
  writing any batch.
- [`references/expert-notes.md`](references/expert-notes.md): the sources' principles with
  timestamps, and the choices where they disagree. Load when a design decision is not covered here.
- [`references/critique.md`](references/critique.md): the rubric for judging a batch, a script or a
  round trip. Load before reporting.
- [`references/gui-paths.md`](references/gui-paths.md): the same operations by palette and hotkey,
  for a human or computer-use agent. Load when a step needs the GUI.
- [`references/sources.md`](references/sources.md): every source with credentials and URLs.
- [`scripts/zb_batch.py`](scripts/zb_batch.py) (agent side: runner, sessions, reports, `-script`,
  Activity oracle, ZScript generators), [`scripts/zb_plugin_ops.py`](scripts/zb_plugin_ops.py)
  (inside ZBrush: per-file steps and plugins), [`scripts/zb_batch_job.py`](scripts/zb_batch_job.py)
  (`-script` entry), [`scripts/zb_goz.py`](scripts/zb_goz.py) (GoZ files and folder, any Python).

© scenario-labs · MIT · scenario-labs/skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set172

The whole set →
scenario-zbrush-hard-surface The scenario-zbrush-hard-surface skill guides an agent through hard-surface work in ZBrush, from Boolean cuts to edge shaping. Use it for armor, mechanical parts, or game assets. CX Codex +1 432installs scenario-godot-multiplayer scenario-godot-multiplayer is a Claude Code skill for planning and testing Godot 4 multiplayer, from object authority and replication to RPC checks and latency tests. CX Codex +1 431installs scenario-zbrush-pose-print scenario-zbrush-pose-print is a Claude Code skill for posing 3D sculpts and preparing models for 3D printing in ZBrush. It provides numerical control over scale and geometry. CX Codex +1 431installs scenario-maya-rigging scenario-maya-rigging guides Maya rigging work for characters, creatures and props, including joints, IK/FK, spaces, matrices and engine skeletons. CX Codex +1 430installs scenario-maya-animation scenario-maya-animation is a Claude Code skill for planning and inspecting character or prop animation in Maya through Python, including motion cycles, dialogue shots, lip sync, and mocap cleanup. CX Codex +1 429installs scenario-maya-deformation scenario-maya-deformation is a Claude Code skill that helps set up character skinning in Maya and fix deformation artifacts, including during skin binding, weight painting, blend shape creation, or deformation tests. CX Codex +1 428installs scenario-maya-pipeline-scripting scenario-maya-pipeline-scripting guides Python pipeline scripting for Autodesk Maya, from mayapy batch runners to strict FBX and USD exports for Unreal or Unity. CX Codex +1 428installs scenario-maya-lookdev scenario-maya-lookdev sets up Arnold shaders, OpenPBR materials, and UDIM textures in Maya. Useful when tuning color spaces, SSS radius, and lookdev turntables. CX Codex +1 427installs

Project sponsors

Companies that keep this analytics open