Blender Modular Assembly

Build complex Blender assets from validated modules.

Skill metadata

Source	Bundled (installed by default)
Path	skills/creative/blender-modular-assembly
Version	2.0.0
Author	Marat Zimnurov and Digit
License	MIT
Platforms	linux, macos, windows
Tags	blender, mcp, 3d, modelling, decomposition, assembly, rigging, morphgraph, training, qa
Related skills	blender-mcp, fts, fts-specify

Reference: full SKILL.md

info

The following is the complete skill definition that Digit loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Blender Modular Assembly Skill

Decompose a complex visual idea into a typed graph of small Blender modules, build those modules incrementally, and compose them only after local QA passes. Do not use this workflow for one-off primitive props where a single short Blender operation is already sufficient.

When to Use

• Build a hero character, mascot, creature, vehicle, building, machine, costume, or other asset with several interacting parts.
• Reproduce concept art while preserving editable parts, rigging, animation, or controlled morphing.
• Repair a monolithic or visually plausible model whose topology, hierarchy, or component identity is unusable.
• Require evidence that every part was built, inspected, and attached before the complete asset was exported.

Prerequisites

• Install and start the blender MCP described by the blender-mcp skill.
• Require the MCP tools get_scene_info, get_object_info, get_viewport_screenshot, and execute_blender_code.
• On a remote renderer, run both Blender and its socket-side bridge on that host. Prefer Digit -> ssh gpu -> blender-mcp -> 127.0.0.1:9876 -> Blender; never expose the unauthenticated Blender socket publicly.
• Keep telemetry disabled. Treat execute_blender_code as arbitrary code execution with the Blender host user's filesystem permissions.

How to Run

Create the graph before creating detailed geometry:

terminal: python <skill-dir>/scripts/form_graph.py new \
  --id archivist-a --output /absolute/work/form-graph.json

Edit the graph with patch, validate it, then ask for the next dependency-safe modules:

terminal: python <skill-dir>/scripts/form_graph.py validate /absolute/work/form-graph.json
terminal: python <skill-dir>/scripts/form_graph.py ready /absolute/work/form-graph.json

Inside execute_blender_code, import the assembly runtime shipped by digitable-lol/blender-mcp:

from assembly.blender_runtime import begin_module, complete_module

ctx = begin_module("/absolute/work/form-graph.json", "hood.rim")
# Create only hood.rim objects here.
complete_module(ctx, [panel_left, panel_top, panel_right])

Read references/form-graph.md before authoring or changing the graph. Read references/authoring-v2.md before sculpt, retopology, baking, rigging, or LOD work. Read references/morph-graph.md before creating a hybrid or transition. Read references/training-traces.md and references/qa-contract.md before the first build or render checkpoint.

Quick Reference

Operation	Command or MCP action
Create graph	scripts/form_graph.py new
Validate dependencies and invariants	scripts/form_graph.py validate
List buildable leaf modules	scripts/form_graph.py ready
Record an external state transition	scripts/form_graph.py set-status
Record a render gate	scripts/form_graph.py checkpoint
Inspect progress	scripts/form_graph.py summary
Build structural training pairs	scripts/formgraph_ranker.py dataset
Train the structural ranker	scripts/formgraph_ranker.py train
Sweep ranker hyperparameters in parallel	scripts/formgraph_ranker.py sweep
Score a proposed decomposition	scripts/formgraph_ranker.py score
Begin/complete inside Blender	assembly.blender_runtime through execute_blender_code
Resolve an allowed form transition	assembly.morphgraph through execute_blender_code
Record accepted and rejected work	assembly.training_trace through execute_blender_code
Inspect the actual scene	get_scene_info, get_object_info
Judge appearance	get_viewport_screenshot plus saved renders

Procedure

1. Freeze the intent contract

Save the source prompt and every approved reference. State the target use, coordinate system, real scale, required views, polygon budgets, deformation needs, material families, and identity invariants. Keep inferred details marked as inferred. A reference image is an appearance constraint, not topology.

When the intent arrives through FTS or Flang, compile the trusted description into this contract before invoking Blender. The language layer may propose modules and parameters; it may not bypass validation, run arbitrary embedded code, or silently widen filesystem and network access.

2. Decompose recursively

Create semantic assemblies first, then split them until every leaf has:

• one generator or modelling technique;
• one attachment interface and owning bone or parent;
• one material responsibility;
• one local acceptance test;
• a bounded rebuild cost.

Split a candidate again when its description contains independent shapes joined by “and”, requires unrelated modifiers, attaches to more than one moving part, or cannot be rejected without discarding already-correct geometry. Preserve repeated parts as parameterized instances, but keep their object identities.

3. Build the support structure first

For characters, construct the anatomical armature, massing volumes, attachment sockets, and naming hierarchy before surface detail. For hard-surface assets, construct reference axes, frames, hinges, and mounting points first. Render the blockout in front, side, three-quarter, and back views. Do not detail a silhouette that has not passed.

An image-to-3D or text-to-3D result may supply one continuous anatomical underbody when its silhouette passes. Treat it as a replaceable module: remove detached islands, keep the largest connected component, retopologize or decimate to a declared budget, and name its provenance. Never let generation bake the face signal, evidence seal, cloak, staff, armour layers, or other identity-bearing assemblies into the underbody. Build those from independent FormGraph leaves so they remain inspectable and rebuildable.

4. Build one ready module at a time

Call ready, choose one leaf, and call begin_module. Make each Blender call idempotent and scoped to that module's collection. Use primitives, curves, bmesh, Geometry Nodes, and non-destructive modifiers before destructive mesh editing. Apply transforms before armature deformation or export.

Never clear or rebuild unrelated passing modules. If a module fails, mark it rejected, retain the evidence, and rebuild only that module.

For a batch of independent forms or props, assign disjoint graph branches to separate Blender MCP ports. Each worker owns one output directory and never opens or saves another worker's .blend. Parallelism changes scheduling, not the dependency or approval gates.

5. Validate locally before composition

Check non-empty geometry, finite transforms, intended dimensions, origin, materials, attachment metadata, manifold requirements, modifier order, and bone ownership. Render a close view when the module carries identity, such as a face, hand, wheel, hinge, or emblem.

Mark the module built, then validated. Only validated modules can satisfy a render checkpoint.

6. Compose by interfaces

Attach modules through declared sockets, bones, pivots, or surfaces. Do not repair a bad fit by hiding intersections inside another mesh. Check contact, clearance, symmetry policy, deformation range, and silhouette after each major assembly stage.

7. Run visual checkpoints

At minimum produce assembled front, side, three-quarter, back, detail, wireframe/rig, and exploded views. Compare at consistent camera, lighting, scale, and pose. Record concrete module-addressed defects; “looks wrong” is not an actionable verdict.

Do not mark an approval checkpoint as passed without inspecting the returned image. A successful screenshot response can still contain a black or stale frame.

8. Sculpt, retopologize, and bake the approved master

Treat the high-resolution sculpt, deformation topology, and runtime meshes as separate artifacts. Sculpt primary mass, secondary anatomy, surface breakup, and identity detail on named layers. Retopologize LOD0 with deliberate loops at every joint and secondary-motion root. Automatic decimation is permitted for derived LODs, never as the final LOD0 topology.

Bake tangent-space normal, ambient occlusion, curvature, thickness, and position maps from the approved sculpt through an explicit cage. Inspect seams, gradients, ray misses, and mirrored tangent behavior before authoring PBR materials. Follow the budgets in references/authoring-v2.md.

9. Rig, animate, morph, optimize, and export

Bind all forms to the semantic CanonicalRig before creating transitions. Add limb IK, retargeting, quantum-gaze look-at, and secondary motion for the mantle, tail, ears, and tool crown. Test extreme poses and every named state. Generate LOD0/LOD1/LOD2 from the approved master while preserving names, material slots, sockets, and animation semantics.

A MorphGraph is an allowlist, not proof that two meshes can transform. Approve a transition only after its module correspondence, common sockets, neutral-pose alignment, identity continuity, and in-between renders pass. A hybrid descriptor is a weighted module policy such as Forge 0.65 + Sentinel 0.35; it is not a linear vertex blend unless both forms also share a verified topology map.

Export an animated GLB and retain the editable .blend, source sculpt, retopology mesh, bakes, textures, graphs, reports, traces, and render evidence.

Re-import the exported GLB into an isolated scene. On a long-lived MCP process, delete every object datablock directly between imports; operator deletion only sees the active view layer and can leave objects in linked collections. Verify the expected armature, required named actions, triangle budget, embedded textures and attachment of every runtime mesh. Record and justify importer-only display helpers separately; never silently count them as authored geometry.

Pitfalls

• Monolithic prompt-to-mesh generation: useful for rough props, not hero identity, rigging, or controlled topology.
• Detail before silhouette: produces expensive rework and visually dense but structurally wrong assets.
• One object per concept: “cloak”, “head”, or “staff” are assemblies, not useful leaf modules.
• Object/bone scale inheritance: apply authored transforms before rigid skinning and verify evaluated dimensions.
• Unbounded MCP scripts: divide code by module and checkpoint; preserve the server connection and return compact JSON evidence.
• Self-approval: programmatic checks can approve structure, never taste or identity. Keep a user or independent visual gate for hero assets.
• Generated identity details: a plausible underbody is not a finished hero. Quantum gaze, evidence seal, current, mantle and props must remain named, independently rebuildable modules.
• Dirty clean-import scenes: bpy.ops.object.delete can miss linked collections in a persistent MCP instance. Remove bpy.data.objects datablocks directly before each validation import.
• Synthetic self-congratulation: the ranker can reject broken graphs, but it cannot label its own render visually accepted. Capture human or independent visual verdicts as immutable trace events.
• Vertex interpolation across incompatible bodies: use socket-preserving module substitution or a field/cage transition until a correspondence map has been validated.

Verification

• form_graph.py validate reports ok: true.
• The dependency graph is acyclic and every attachment target exists.
• No leaf combines unrelated generators, attachments, or QA duties.
• Every built object carries assembly.module_id metadata.
• Every required module is validated; rejected modules retain notes.
• Required render checkpoints include assembled, detail, rig, and exploded evidence and have been visually inspected.
• The armature and extreme-pose tests preserve attachments and volume.
• Canonical sockets survive retargeting, every LOD, and every allowed morph.
• Normal/AO/curvature bakes pass seam, cage, and tangent-space inspection.
• Accepted and rejected decisions are present in a durable training trace.
• A clean GLB import contains the expected rig and every required named action, with every authored runtime mesh bound to the rig.
• .blend, animated .glb, FormGraph, statistics, and QA renders exist.
• The approved asset, not an earlier draft, is the one selected for runtime.