Blockbench Use
Orchestrator for Blockbench MCP work. Load this before touching the 3D scene so the right sub-skills load and the right pre-flight checks run.
Rule
Any request that will call an mcp__blockbench__* tool to create or modify content must go through this skill first.
Steps, in order:
- Classify the request → pick one or more sub-skills (table below).
- Pre-flight → confirm a project is open and the format is correct (see "Pre-flight checks").
- Load the sub-skill(s) via the Skill tool.
- Checkpoint before risk → call
save_checkpoint for multi-step edits that might need rollback.
- Execute the sub-skill's workflow.
- Close the loop → screenshot, validate (Hytale), or export if the user asked for a deliverable.
Skill routing table
Pick by primary intent. When the task spans domains, load all relevant skills before starting.
| User intent |
Primary skill |
Also load when… |
| Build cubes, meshes, groups, hierarchy |
blockbench-modeling |
needs texture → blockbench-texturing |
| Paint, fill, draw, brush, layers, UV |
blockbench-texturing |
channel-aware (normal/MER) → blockbench-pbr-materials |
| Keyframes, bone rigs, walk/idle/attack |
blockbench-animation |
bones need geometry first → blockbench-modeling |
.texture_set.json, normal/height/MER |
blockbench-pbr-materials |
textures not yet drawn → blockbench-texturing |
.blockymodel, .blockyanim, attachments, quads, stretch, shading modes |
blockbench-hytale |
modeling/animation parts → those skills |
| "What tools are available?" / unclear scope |
blockbench-mcp-overview |
— |
| Write a Blockbench JS plugin (not use MCP) |
blockbench-plugins (from blockbench-development/) |
— |
Skip this skill for pure research questions (API docs, "how does Blockbench work?"). Go straight to blockbench-mcp-overview.
Pre-flight checks
Run before any mutation. One round of list_outline + list_textures is usually enough.
- Is a project open? If no project, call
create_project first (format from the routing table below).
- Is the format correct for the task?
- Cube modeling (Minecraft) →
bedrock_block, java_block, bedrock
- Mesh/freeform →
free, modded_entity, optifine_entity
- Hytale character →
hytale_character (64px)
- Hytale prop →
hytale_prop (32px)
- Generic →
generic or free
- What's already there? Use
list_outline (structure) + list_textures (materials). Prefer find_elements_by_criteria / filter_by_material over dumping the whole outline for large projects.
- Hytale project? Run
hytale_validate_model at the end; never silently exceed 255 nodes.
Multi-skill workflow compositions
"Create a Minecraft character with a walk cycle"
blockbench-modeling → bones + cubes
blockbench-texturing → skin texture
blockbench-animation → walk cycle keyframes
# finally:
capture_screenshot → preview
export_model: codec_id="project" → save .bbmodel
"Make a Bedrock RTX block"
blockbench-modeling → single cube
blockbench-texturing → color map
blockbench-pbr-materials → normal + MER + texture_set.json
# finally:
hytale_validate_model → (skip — not Hytale)
capture_screenshot
"Build a Hytale character with attachments"
blockbench-hytale → read first: format, node limits, pieces
blockbench-modeling → geometry in character format
blockbench-animation → optional keyframes (60 FPS)
# separately per attachment collection:
blockbench-hytale → hytale_set_attachment_piece on bones
# finally:
hytale_validate_model → node count, stretch, shading
export_model: codec_id="blockymodel"
"Retexture an existing model"
# Pre-flight: find everything that uses the old texture
filter_by_material: texture="old_skin"
# Load:
blockbench-texturing → paint/create replacement
# Swap references:
apply_texture per match (from filter_by_material results)
Safety & efficiency rules (apply in every session)
- Checkpoint before risk. For any workflow of 3+ mutations, call
save_checkpoint: name="<descriptive>" first. If the result is wrong, undo: steps=N back.
- Filter, don't dump. Prefer
find_elements_by_criteria, filter_by_material, or select_all_of_type over list_outline when you know the shape of what you want. Large outlines blow context.
- Respect the format. Don't call Hytale tools on a non-Hytale project — they will error. Check
Format.id via risky_eval or hytale_get_format_info if unsure.
- Screenshot after meaningful changes.
capture_screenshot confirms the model looks right. Do it at milestones, not every edit.
- Export only when the user asks for a deliverable. Use
list_export_formats first to pick the right codec, then export_model with a path (or content-only if the user just wants to see it).
- Never call
trigger_action: action="undo" or "redo". Use the dedicated undo / redo tools — they return which actions were traversed.
- Name everything. Descriptive names make
find_elements_by_criteria and filtering work later.
When to load blockbench-mcp-overview
Load it instead of a specialized skill when:
- The user's intent is ambiguous ("help me with this model")
- The tool call count will be small (<5) and spans multiple domains
- The user is asking about capabilities, not executing
Otherwise prefer the specialized skills — they have concrete examples and return shapes.
What this skill does NOT cover
- Blockbench plugin development (writing
.js plugins) → blockbench-plugins
- MCP server development (adding tools to this repo) → not in this skill set
- General 3D theory / THREE.js / rendering internals → out of scope
1---
2name: blockbench-use
3description: "MANDATORY prerequisite — invoke BEFORE any mcp__blockbench__* tool call that creates, modifies, or exports Blockbench content. Orchestrates the other blockbench-* skills (modeling, texturing, animation, PBR, Hytale, MCP overview). Trigger on: 3D model/texture/animation creation or edits in Blockbench; calls to mcp__blockbench__* tools; phrases like 'build a Minecraft model', 'paint a texture', 'animate this rig', 'export the model'. Dispatches to the right sub-skill(s), enforces pre-flight checks (project open, format, outline), wraps risky work in checkpoints, and ensures exports close the loop."
4metadata:
5 source: https://skillmd.com/skills/jasonjgardner/blockbench-use
6---
7
8# Blockbench Use
9
10Orchestrator for Blockbench MCP work. Load this **before** touching the 3D scene so the right sub-skills load and the right pre-flight checks run.
11
12## Rule
13
14Any request that will call an `mcp__blockbench__*` tool to create or modify content **must** go through this skill first.
15
16Steps, in order:
17
181. **Classify the request** → pick one or more sub-skills (table below).
192. **Pre-flight** → confirm a project is open and the format is correct (see "Pre-flight checks").
203. **Load the sub-skill(s)** via the Skill tool.
214. **Checkpoint before risk** → call `save_checkpoint` for multi-step edits that might need rollback.
225. **Execute** the sub-skill's workflow.
236. **Close the loop** → screenshot, validate (Hytale), or export if the user asked for a deliverable.
24
25## Skill routing table
26
27Pick by primary intent. When the task spans domains, load **all** relevant skills before starting.
28
29| User intent | Primary skill | Also load when… |
30|---|---|---|
31| Build cubes, meshes, groups, hierarchy | `blockbench-modeling` | needs texture → `blockbench-texturing` |
32| Paint, fill, draw, brush, layers, UV | `blockbench-texturing` | channel-aware (normal/MER) → `blockbench-pbr-materials` |
33| Keyframes, bone rigs, walk/idle/attack | `blockbench-animation` | bones need geometry first → `blockbench-modeling` |
34| `.texture_set.json`, normal/height/MER | `blockbench-pbr-materials` | textures not yet drawn → `blockbench-texturing` |
35| `.blockymodel`, `.blockyanim`, attachments, quads, stretch, shading modes | `blockbench-hytale` | modeling/animation parts → those skills |
36| "What tools are available?" / unclear scope | `blockbench-mcp-overview` | — |
37| Write a Blockbench JS plugin (not use MCP) | `blockbench-plugins` (from `blockbench-development/`) | — |
38
39**Skip this skill** for pure research questions (API docs, "how does Blockbench work?"). Go straight to `blockbench-mcp-overview`.
40
41## Pre-flight checks
42
43Run before any mutation. One round of `list_outline` + `list_textures` is usually enough.
44
451. **Is a project open?** If no project, call `create_project` first (format from the routing table below).
462. **Is the format correct for the task?**
47 - Cube modeling (Minecraft) → `bedrock_block`, `java_block`, `bedrock`
48 - Mesh/freeform → `free`, `modded_entity`, `optifine_entity`
49 - Hytale character → `hytale_character` (64px)
50 - Hytale prop → `hytale_prop` (32px)
51 - Generic → `generic` or `free`
523. **What's already there?** Use `list_outline` (structure) + `list_textures` (materials). Prefer `find_elements_by_criteria` / `filter_by_material` over dumping the whole outline for large projects.
534. **Hytale project?** Run `hytale_validate_model` at the end; never silently exceed 255 nodes.
54
55## Multi-skill workflow compositions
56
57### "Create a Minecraft character with a walk cycle"
58
59```
60blockbench-modeling → bones + cubes
61blockbench-texturing → skin texture
62blockbench-animation → walk cycle keyframes
63# finally:
64capture_screenshot → preview
65export_model: codec_id="project" → save .bbmodel
66```
67
68### "Make a Bedrock RTX block"
69
70```
71blockbench-modeling → single cube
72blockbench-texturing → color map
73blockbench-pbr-materials → normal + MER + texture_set.json
74# finally:
75hytale_validate_model → (skip — not Hytale)
76capture_screenshot
77```
78
79### "Build a Hytale character with attachments"
80
81```
82blockbench-hytale → read first: format, node limits, pieces
83blockbench-modeling → geometry in character format
84blockbench-animation → optional keyframes (60 FPS)
85# separately per attachment collection:
86blockbench-hytale → hytale_set_attachment_piece on bones
87# finally:
88hytale_validate_model → node count, stretch, shading
89export_model: codec_id="blockymodel"
90```
91
92### "Retexture an existing model"
93
94```
95# Pre-flight: find everything that uses the old texture
96filter_by_material: texture="old_skin"
97# Load:
98blockbench-texturing → paint/create replacement
99# Swap references:
100apply_texture per match (from filter_by_material results)
101```
102
103## Safety & efficiency rules (apply in every session)
104
1051. **Checkpoint before risk.** For any workflow of 3+ mutations, call `save_checkpoint: name="<descriptive>"` first. If the result is wrong, `undo: steps=N` back.
1062. **Filter, don't dump.** Prefer `find_elements_by_criteria`, `filter_by_material`, or `select_all_of_type` over `list_outline` when you know the shape of what you want. Large outlines blow context.
1073. **Respect the format.** Don't call Hytale tools on a non-Hytale project — they will error. Check `Format.id` via `risky_eval` or `hytale_get_format_info` if unsure.
1084. **Screenshot after meaningful changes.** `capture_screenshot` confirms the model looks right. Do it at milestones, not every edit.
1095. **Export only when the user asks for a deliverable.** Use `list_export_formats` first to pick the right codec, then `export_model` with a `path` (or content-only if the user just wants to see it).
1106. **Never call `trigger_action: action="undo"` or `"redo"`.** Use the dedicated `undo` / `redo` tools — they return which actions were traversed.
1117. **Name everything.** Descriptive names make `find_elements_by_criteria` and filtering work later.
112
113## When to load `blockbench-mcp-overview`
114
115Load it instead of a specialized skill when:
116
117- The user's intent is ambiguous ("help me with this model")
118- The tool call count will be small (<5) and spans multiple domains
119- The user is asking about capabilities, not executing
120
121Otherwise prefer the specialized skills — they have concrete examples and return shapes.
122
123## What this skill does NOT cover
124
125- **Blockbench plugin development** (writing `.js` plugins) → `blockbench-plugins`
126- **MCP server development** (adding tools to this repo) → not in this skill set
127- **General 3D theory / THREE.js / rendering internals** → out of scope