Skip to content
Back to search

blender-assembly

"Use this skill whenever building, assembling, or creating any 3D model in Blender via MCP tools (mcp__blender__execute_blender_code). Covers all object types: furniture, vehicles, architecture, characters, props, mechanical parts, scenes. Trigger any time Blender Python code will create geometry with primitives, bmesh, or modifiers. Even simple objects benefit from correct primitive math and verification. Always invoke this skill before writing any Blender geometry code - it prevents the three most common geometry bugs that cause exploded-looking models."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/profrino--blender-mcp-assembly-skill/badge.svg)](/listings/profrino--blender-mcp-assembly-skill)

HTML

<a href="/listings/profrino--blender-mcp-assembly-skill"><img src="/api/listings/profrino--blender-mcp-assembly-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 222 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: blender-assembly
  3. description: "Use this skill whenever building, assembling, or creating any 3D model in Blender via MCP tools (mcp__blender__execute_blender_code). Covers all object types: furniture, vehicles, architecture, characters, props, mechanical parts, scenes. Trigger any time Blender Python code will create geometry with primitives, bmesh, or modifiers. Even simple objects benefit from correct primitive math and verification. Always invoke this skill before writing any Blender geometry code - it prevents the three most common geometry bugs that cause exploded-looking models."
  4. ---
  5. # Blender Assembly Skill
  6. This skill prevents geometry errors when building 3D models in Blender via MCP. It addresses three bugs that are easy to make and hard to spot until the model looks wrong:
  7. 1. **Cube size math** — `primitive_cube_add(size=1)` creates vertices at ±0.5, so `scale=0.4` gives half-extent 0.2, not 0.4. This silently halves every dimension, misplacing all connected parts.
  8. 2. **Euler rotation on cylinders** — rotating a cylinder to point in a direction using Euler angles frequently points it along the wrong axis due to XYZ rotation order.
  9. 3. **Invisible gaps** — parts placed "near" each other with no geometric overlap look exploded when rendered. Even a 5mm gap is visible at model scale.
  10. ## Phase 1: Connection Planning (before any code)
  11. Create a **connection map** listing every joint before writing any geometry. This forces correct thinking about where parts touch.
  12. For each joint, write:
  13. - The two parts that connect
  14. - Which face/edge of each meets the other
  15. - The target overlap (minimum 0.005m / 5mm)
  16. ```
  17. Connection Map:
  18. tabletop_bottom (Z=0.73) <-> leg_top (Z=0.74) overlap: 0.01m on Z
  19. leg_bottom (Z=0.01) <-> floor (Z=0.00) sits on floor
  20. drawer_back <-> desk_body_front overlap: 0.01m on Y
  21. ```
  22. Write this as a comment block in your first code cell, before any bpy calls.
  23. ## Phase 2: Geometry Creation Rules
  24. ### Rule 1: Always Use size=2 for Cube Primitives
  25. A cube with `size=S` has vertices at `±S/2`. After `scale=K`, the half-extent is `K * S/2` — **not** `K`.
  26. **Always use `size=2`.** With `size=2`, vertices are at ±1, so after `scale=K` the half-extent equals `K` directly. The math is transparent and the factor-of-2 error disappears.
  27. ```python
  28. # CORRECT — size=2, scale = desired half-extent
  29. bpy.ops.mesh.primitive_cube_add(size=2, location=(0, 0, 0.75))
  30. obj.scale = (0.60, 0.30, 0.02) # box is 1.2m wide, 0.6m deep, 0.04m tall
  31. # WRONG — size=1, scale misread as full extent
  32. bpy.ops.mesh.primitive_cube_add(size=1, location=(0, 0, 0.75))
  33. obj.scale = (0.60, 0.30, 0.02) # box is only 0.6m wide — half of intended!
  34. ```
  35. Cylinders and spheres use `radius` which is already the actual radius — no conversion needed.
  36. ### Rule 2: Use bmesh for Directional Geometry — Never Rotate Cylinders
  37. Never create a cylinder and rotate it to point in a direction. Euler rotation order (XYZ) makes this fail silently — the cylinder often ends up on the wrong axis.
  38. For any geometry that must span from point A to point B (legs, beams, axles, supports, pipes, rails), **build it with bmesh using explicit vertex positions**:
  39. ```python
  40. import bpy, bmesh, math
  41. def make_beam(name, start, end, hw=0.012, hh=0.010):
  42. """Build a rectangular beam from start to end — no rotations needed."""
  43. dx, dy, dz = end[0]-start[0], end[1]-start[1], end[2]-start[2]
  44. L = math.sqrt(dx*dx + dy*dy + dz*dz)
  45. if L < 1e-6:
  46. return None
  47. fx, fy, fz = dx/L, dy/L, dz/L
  48. # Right vector (cross forward with world-up; fallback to world-X if beam is vertical)
  49. ux, uy, uz = (0,0,1) if abs(fz) < 0.99 else (1,0,0)
  50. rx = fy*uz-fz*uy; ry = fz*ux-fx*uz; rz = fx*uy-fy*ux
  51. rL = math.sqrt(rx*rx+ry*ry+rz*rz); rx,ry,rz = rx/rL,ry/rL,rz/rL
  52. upx = ry*fz-rz*fy; upy = rz*fx-rx*fz; upz = rx*fy-ry*fx
  53. mesh = bpy.data.meshes.new(name)
  54. obj = bpy.data.objects.new(name, mesh)
  55. bpy.context.collection.objects.link(obj)
  56. bpy.context.view_layer.objects.active = obj
  57. obj.select_set(True)
  58. bm = bmesh.new()
  59. verts = []
  60. for base in [start, end]:
  61. for sx, sy in [(-1,-1),(1,-1),(1,1),(-1,1)]:
  62. verts.append(bm.verts.new((
  63. base[0]+rx*hw*sx+upx*hh*sy,
  64. base[1]+ry*hw*sx+upy*hh*sy,
  65. base[2]+rz*hw*sx+upz*hh*sy,
  66. )))
  67. v = verts
  68. for f in [(0,1,5,4),(1,2,6,5),(2,3,7,6),(3,0,4,7),(0,3,2,1),(4,5,6,7)]:
  69. bm.faces.new([v[i] for i in f])
  70. bm.to_mesh(mesh); bm.free()
  71. return obj
  72. ```
  73. Use for: chair/table legs, beams, axles, pipes, frame members, railings, any angled strut.
  74. Skip for: vertical posts, wheels, hubs — anything aligned with a world axis where no rotation is needed.
  75. ### Rule 3: Always Call transform_apply Immediately After Setting Scale
  76. When creating objects in a loop, `bpy.context.active_object` can silently reference the wrong object by the end of the loop, causing a scale assignment to fail or apply to the wrong mesh. Call `transform_apply` immediately after every scale assignment — inside the loop, before anything else:
  77. ```python
  78. # CORRECT
  79. bpy.ops.mesh.primitive_cube_add(size=2, location=(x, y, z))
  80. obj = bpy.context.active_object
  81. obj.name = name
  82. obj.scale = (sx, sy, sz)
  83. bpy.ops.object.transform_apply(scale=True) # ← immediately, inside the loop
  84. # WRONG — scale may silently not apply
  85. obj.scale = (sx, sy, sz)
  86. # ... more operations ...
  87. bpy.ops.object.transform_apply(scale=True) # too late; active_object may have changed
  88. ```
  89. ### Rule 4: Derive Spanning Dimensions from Verified Neighbour Bounds
  90. Never hardcode a dimension for a part that must reach between two existing parts. Hardcoded values drift from actual geometry. Instead, call `verify_bounds()` on both neighbours and compute the required size from their real extents:
  91. ```python
  92. # CORRECT — measure first, then size the new part
  93. b_a = verify_bounds("Part_A")
  94. b_b = verify_bounds("Part_B")
  95. half_span = (b_b['x'][1] - b_a['x'][0]) / 2 # actual half-width needed to bridge A and B
  96. # WRONG — dimension set independently of actual neighbour positions
  97. half_span = 0.28 # guessed; will be wrong if neighbours shifted even slightly
  98. ```
  99. Apply this rule whenever one part must cover, fill, or connect two others on any axis. Always measure the gap from real bounds; never guess.
  100. ### Rule 5: Compensate for Subsurf Shrinkage
  101. Subdivision surface modifiers pull geometry inward. A box spanning 0.0–0.30m may only reach 0.26m after level-2 subsurf.
  102. **Extend geometry 10–15% past the target boundary** before applying subsurf, then verify:
  103. ```python
  104. target_reach = 0.28
  105. build_to = target_reach * 1.13 # 13% longer to compensate for shrinkage
  106. ```
  107. Alternative: use bevel modifier instead of subsurf for structural parts — it adds smooth edges without shrinking the shape.
  108. ## Phase 3: Verify After Every Part
  109. Call these helpers after creating each part. Catching a gap immediately is far cheaper than debugging an exploded model later.
  110. ```python
  111. def verify_bounds(name):
  112. """Print and return world-space bounding box."""
  113. obj = bpy.data.objects[name]
  114. vs = [obj.matrix_world @ v.co for v in obj.data.vertices]
  115. b = {
  116. 'x': (min(v.x for v in vs), max(v.x for v in vs)),
  117. 'y': (min(v.y for v in vs), max(v.y for v in vs)),
  118. 'z': (min(v.z for v in vs), max(v.z for v in vs)),
  119. }
  120. print(f"{name}: X[{b['x'][0]:.4f},{b['x'][1]:.4f}]"
  121. f" Y[{b['y'][0]:.4f},{b['y'][1]:.4f}]"
  122. f" Z[{b['z'][0]:.4f},{b['z'][1]:.4f}]")
  123. return b
  124. def verify_overlap(name_a, name_b, axis='z', min_overlap=0.005):
  125. """Confirm two parts physically overlap on the given axis."""
  126. a = verify_bounds(name_a)
  127. b = verify_bounds(name_b)
  128. overlap = min(a[axis][1], b[axis][1]) - max(a[axis][0], b[axis][0])
  129. ok = overlap >= min_overlap
  130. print(f" {name_a} <-> {name_b} [{axis.upper()}]: "
  131. f"{'OK' if ok else 'GAP WARNING'} ({overlap:.4f}m)")
  132. return overlap
  133. ```
  134. Run `verify_overlap` for **every joint** in your connection map before moving to the next part. If it shows a gap, fix the position before continuing.
  135. ## Phase 4: Finalization
  136. Apply to every mesh object:
  137. ```python
  138. def finalize(name):
  139. """Apply transforms, set origin to geometry, shade smooth for the named object."""
  140. obj = bpy.data.objects[name]
  141. bpy.ops.object.select_all(action='DESELECT') # scope the ops below to `obj` only
  142. bpy.context.view_layer.objects.active = obj
  143. obj.select_set(True)
  144. bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)
  145. bpy.ops.object.origin_set(type='ORIGIN_GEOMETRY', center='MEDIAN')
  146. bpy.ops.object.shade_smooth()
  147. bpy.ops.object.select_all(action='DESELECT')
  148. return obj
  149. def audit_all():
  150. """Final check — all parts should have rotation (0,0,0) and scale (1,1,1)."""
  151. meshes = sorted([o for o in bpy.data.objects if o.type == 'MESH'], key=lambda o: o.name)
  152. all_ok = True
  153. for obj in meshes:
  154. rot = tuple(round(c, 3) for c in obj.rotation_euler)
  155. scl = tuple(round(c, 3) for c in obj.scale)
  156. ok = rot == (0.0,0.0,0.0) and scl == (1.0,1.0,1.0)
  157. if not ok: all_ok = False
  158. print(f" [{'OK' if ok else '!!'}] {obj.name:30s} rot={rot} scl={scl}")
  159. print(f"\nAll transforms clean: {all_ok}")
  160. return all_ok
  161. ```
  162. ## Workflow Checklist
  163. Every Blender model, every time:
  164. 1. **Plan connections** — write the connection map first, before any bpy code
  165. 2. **Use `size=2`** for all cube primitives — scale = actual half-extent directly
  166. 3. **Use `make_beam()`** for any geometry pointing from A to B — no Euler rotations
  167. 4. **`transform_apply(scale=True)` inside every loop** — call it immediately after `obj.scale = (...)`, never outside the loop
  168. 5. **Derive spanning dimensions from `verify_bounds()`** — never hardcode a size that must match a neighbour; measure the actual extent and compute from it
  169. 6. **Overshoot subsurf** — extend 10–15% past target; verify bounds after apply
  170. 7. **`verify_bounds()`** — print world-space extents after every single part
  171. 8. **`verify_overlap()`** — check every joint; fix gaps before moving on
  172. 9. **`finalize()`** — apply transforms, set origin, shade smooth on every part
  173. 10. **`audit_all()`** — confirm rotation=0 and scale=1 across the whole scene
README.md · README · 48 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Blender-MCP-Assemply-Skill
  2. Blender Assembly is a geometry-building skill for creating reliable 3D models in Blender via MCP. It helps prevent common modelling errors by planning object connections, using correct primitive scaling, avoiding faulty cylinder rotations, verifying overlaps, and auditing final transforms.
  3. ## Before vs After
  4. The image below shows how the Blender MCP Assembly Skill helps an AI agent move from a disconnected chair assembly to a cleaner, connected Blender model.
  5. ![Before vs After](Before%20vs%20After.png)
  6. ## What is included in the skill?
  7. The Blender MCP Assembly Skill provides a practical workflow for any AI agent creating geometry in Blender through MCP tools. It guides the agent before, during, and after model creation, starting with connection planning. Before writing Blender Python code, the agent maps how each part of the model should physically connect, including joints, contact faces, and minimum overlaps. This helps reduce disconnected or “exploded” models by making the assembly logic explicit from the beginning.
  8. The skill then defines geometry creation rules for building cleaner and more reliable models. It instructs agents to use `size=2` for cube primitives so scale values match real half-extents, avoid Euler rotations for cylinders or directional parts, and use bmesh-based geometry for beams, supports, rails, pipes, legs, or any element that must span between two points. It also requires transforms to be applied immediately after scaling, especially inside loops, to reduce the risk of Blender applying changes to the wrong object.
  9. A key part of the skill is verification. It includes helper functions such as `verify_bounds()` and `verify_overlap()` so the agent can check the real world-space size and position of each part. Instead of guessing dimensions, the agent is encouraged to measure existing geometry and derive new dimensions from verified bounds. This makes the modelling process more reliable and helps reduce hidden gaps, alignment issues, and scaling errors.
  10. Finally, the skill includes a finalisation and audit stage. Functions such as `finalize()` and `audit_all()` help apply transforms, set origins, smooth geometry, and confirm that mesh objects have clean rotation and scale values. The result is a more predictable Blender MCP workflow for AI agents, producing models that are better connected, correctly scaled, and easier to inspect or modify later.
  11. ## How to Use
  12. The skill is defined in `SKILL.md`. To use it, add `SKILL.md` to your AI agent's skill or prompt library so it is automatically applied whenever Blender MCP geometry code is being written.
  13. ### GitHub Copilot
  14. Copy `SKILL.md` into your repository and reference it from `.github/copilot-instructions.md`:
  15. ```
  16. When creating geometry in Blender via MCP, follow the workflow in SKILL.md.
  17. ```
  18. GitHub Copilot will read `.github/copilot-instructions.md` automatically for any repository that contains it.
  19. ### Other AI Agents
  20. Place `SKILL.md` in the same directory as your agent's skill files. The `description` field in the YAML front matter is used by agents that support skill routing — it tells the agent when to invoke the skill automatically.
  21. ### Manual Use
  22. Copy the relevant sections of `SKILL.md` into your system prompt or paste them directly into your Blender MCP session before asking an AI agent to generate geometry.
  23. ## Tutorial
  24. Watch the full tutorial on YouTube to see how the **Blender MCP Assembly Skill** can be used in practice with Blender and AI agents.
  25. In this video, I explain the purpose of the skill, how it helps prevent common Blender geometry problems, and how it can support more reliable AI-generated 3D modelling workflows through MCP.
  26. [Watch the tutorial on YouTube](https://youtu.be/fsLkJNEtsTw?si=Yn5LQF2USk_PpWG1)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.