text-to-blender

name	text-to-blender
description	Drive Blender from natural language. Converts plain-English requests ("model a sword and render it with cinematic lighting", "make this glass look frosted", "set up three-point lighting", "export this scene as glTF for the web") into Blender Python code executed via the Blender MCP server. Acts as the orchestrator that picks and chain-loads specialised sub-skills (blender-modeling, blender-materials, blender-lighting, blender-cameras, blender-rendering, blender-animation, blender-export, wireframe-to-3d, blender-pro-workflow, blender-skill-harmonizer, quality-refinement-autoloop). Use this skill whenever the user wants Claude to do anything in Blender, including creating geometry, applying materials, lighting a scene, framing a camera, rendering, animating, or exporting. Make sure to invoke this skill even if the user does not say "Blender" — also covers requests like "create a 3D model of...", "render this...", "make a glTF from...", "set up a scene with...", or any 3D-creation task. Requires the Blender MCP addon (ahujasid/blender-mcp) running on port 9876.
when_to_use	User asks for any 3D creation, modification, lighting, rendering, animation, or export task. Anything involving Blender or that should reasonably be done in Blender.
allowed-tools	Read Bash Glob Grep mcp__blender__execute_blender_code mcp__blender__get_scene_info mcp__blender__get_object_info mcp__blender__get_viewport_screenshot

Text-to-Blender Orchestrator

Turn plain-English requests into Blender work. You are the conductor: read the request, decide which sub-skills to chain-load, sequence them in the right order, and execute via the Blender MCP.

Multi-skill harmonization

For complex tasks that trigger multiple Blender skills, especially reference/template/brand work, load blender-skill-harmonizer before choosing the execution order. It owns precedence, handoff artifacts, and conflict policy.

If the user rejects an output as sub-par, says the same issue is recurring, or asks to improve the skill stack before retrying, load quality-refinement-autoloop before further product work. It turns evidence into a sanitized reusable lesson, patches generic skills/docs/versioning when explicitly requested, and only then resumes the Blender repair loop.

How this skill works

The user speaks in tasks ("render a hero shot of a sword on a stone"); you:

1. Identify intent → which capabilities are needed (modeling? materials? lighting? rendering? export?).
2. Check prerequisites → MCP server reachable, scene state.
3. Reset world to a known-good baseline (see World reset below) — prevents leftover broken HDRI / Environment Texture nodes from previous runs corrupting the render.
4. Look up real-world dimensions for the subject (references/common-object-dimensions.md) BEFORE generating Python. A "sword" has specific proportions; a "chair" has specific proportions; do not guess.
5. Route to sub-skills → load the relevant ones via Read and follow their instructions.
6. Sequence the work in the order pros use (see references/assembly-order.md).
7. Execute generated Python via mcp__blender__execute_blender_code.
8. Validate with mcp__blender__get_scene_info, get_object_info, AND get_viewport_screenshot — see Visual validation checkpoint below. Numerical validation alone is not enough: the API can report success while geometry is grossly wrong.
9. Iterate — if the visual check shows an obvious problem (subject barely visible, wrong proportions, wrong orientation), fix and re-render BEFORE reporting success.
10. Report to the user with concrete numbers AND a path to the proof render they can inspect.

World reset (always step 3, before any composition)

Previous tests can leave the scene's world in a broken state — particularly an Environment Texture node with image=None cascading into Background, which produces a magenta-flooded render. Reset world to a neutral baseline at the start of every scene-build:

def reset_world(scene, color=(0.04, 0.04, 0.05, 1.0), strength=0.4):
    world = scene.world
    world.use_nodes = True
    nodes = world.node_tree.nodes
    for n in list(nodes):
        nodes.remove(n)
    output = nodes.new('ShaderNodeOutputWorld')
    bg = nodes.new('ShaderNodeBackground')
    bg.inputs['Color'].default_value = color
    bg.inputs['Strength'].default_value = strength
    world.node_tree.links.new(bg.outputs['Background'], output.inputs['Surface'])

If the user wants HDRI lighting, override this AFTER it runs (load the actual .hdr file and verify env.image is not None).

Visual validation checkpoint (always between steps 8 and 10)

After rendering, always:

1. Call mcp__blender__get_viewport_screenshot (or read the rendered file with Read).
2. Visually verify against the user's request. Specifically:
   • Subject is visible and recognisable (not a thin streak, not magenta-flooded, not entirely in shadow)
   • Proportions match the real-world reference dimensions for that subject
   • Composition is reasonable (subject in frame, not clipped at edges, not microscopic in one corner)
   • Materials have visible variation (not perfectly flat plastic-looking surfaces) — for production-quality scenes, add procedural texture nodes
3. If the render is obviously wrong, do NOT report success. Iterate: identify the specific problem, fix it, re-render, re-check.

A render passing every numerical check (object count, vertex count, file size, no error messages) can still look completely wrong. The user only sees the picture. Make sure the picture matches the request before declaring done.

Set viewport to Material Preview mode (last step before reporting)

The user is often looking at Blender's viewport, not the rendered file. Blender defaults the viewport to Solid shading mode which ignores all materials and shows everything as flat grey. After scene assembly, switch the viewport to Material Preview so the user actually sees the materials they got:

import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'           # or 'RENDERED' for full quality
                space.shading.use_scene_lights = True
                space.shading.use_scene_world = True

Skip this only when the user has explicitly asked you to leave the viewport alone.

Real-world dimension lookup

Before sizing any subject from natural language, consult references/common-object-dimensions.md. It lists realistic proportions for common requests:

Subject	Total	Notes
One-handed sword	~95-100 cm long	Blade 78cm × 4.5cm × 0.8cm; guard 20cm × 2.5cm; grip 13cm; pommel 5.6cm
Chair	seat ~45cm × 45cm × 4cm	Seat height 45cm; back ~45cm tall
Bottle	25-30cm tall	Body ø8-10cm; neck ø2-3cm

The full reference list lives in references/common-object-dimensions.md. Do not guess.

Prerequisites — always check first

Before any work, verify:

1. Blender MCP is reachable. Call mcp__blender__get_scene_info. If it errors with "Could not connect to Blender":

   "Blender's MCP addon isn't running. Start Blender, enable the BlenderMCP addon (port 9876 default), then re-run."

   Stop and ask the user to fix this.

2. Scene state. get_scene_info returns the current objects. Decide:

   • Empty scene? → Start fresh; build from primitives.
   • Existing objects? → Operate on them; do NOT delete unless asked.
   • Default cube only? → Probably safe to delete (bpy.ops.object.delete()).

3. The user's actual request. If ambiguous, ask one question. Otherwise proceed with sensible defaults.

Intent → sub-skill routing table

For each intent the user expresses, load (via Read) the matching sub-skill's SKILL.md and follow its patterns. Multiple intents = chain multiple sub-skills.

User intent (paraphrased)	Load these sub-skills	Order
"Make a 3D model of X"	blender-modeling	1st
"From this wireframe drawing"	wireframe-to-3d	1st
"Use these materials / make it look like X"	blender-materials	After modeling
"Light it / studio setup / cinematic"	blender-lighting	After geometry exists
"Hero shot / camera angle / DoF"	blender-cameras	After lighting
"Render it / produce an image"	blender-rendering	Last visual step
"Animate / move / rotate over time"	blender-animation	After geometry
"Export as glTF / FBX / OBJ / for web / for Unity"	blender-export	Final step
"Set up a scene / production-quality result"	blender-pro-workflow	First — guides everything
"I'm new / not sure where to start"	blender-pro-workflow	First
"This is sub-par / still wrong / same issue again"	quality-refinement-autoloop, then blender-skill-harmonizer	First — learn, sanitize, patch, then retry
"Match these templates / wireframes / textures exactly"	blender-skill-harmonizer, then reference-specific fit skills	First — establish source-of-truth gates

Multi-intent example: "Model a sword with materials, light it dramatically, and export as glTF" →

1. blender-pro-workflow (sequencing strategy)
2. blender-modeling (sword geometry)
3. blender-materials (steel + leather grip)
4. blender-lighting (dramatic 1-point or rim setup)
5. blender-export (glTF settings)

Pro assembly order (when in doubt)

This order minimizes rework. When the user gives a multi-step request, follow it:

1. Reference + plan — note the goal.
2. Block-out — primitives + camera + composition. Cheapest to iterate.
3. Camera lock — pick focal length, frame the shot.
4. Light v1 — three-point (key/fill/rim) before any material work. Light defines mood.
5. Refine geometry — replace primitives with real models.
6. Materials v1 — flat colors first, get values right.
7. Light v2 — color + ratios.
8. Detail pass — only after the above is right.
9. Final render — production samples + denoise.
10. Composite — color grade, glare, vignette.
11. Export — for the target platform.

Source: references/assembly-order.md (deeper rationale).

Code-execution rules — non-negotiable

When emitting Python for mcp__blender__execute_blender_code:

• Each call is a fresh namespace. Only bpy is pre-imported; re-import math, bmesh, numpy, etc. each call.
• Identify objects by stable name, never by Python variable. bpy.data.objects['GEO-sword'] works across calls; a sword = ... assignment does not.
• Print structured output so you can parse it back. End each chunk with print(f"...") reporting what changed (object names, vertex counts, file paths).
• Chunk the work. 180-second timeout per call. Don't dump 500 lines in one call — split into ~5–20-line chunks.
• Use Blender Studio naming conventions for everything you create: GEO-, MAT-, LGT-, CAM-, ARM-, COL-. Never leave anything as Cube.027.

Standard skeleton for every operation

import bpy
# (re-import other modules here as needed)

# 1. Scope: identify or create objects by NAME
obj = bpy.data.objects.get('GEO-target') or bpy.data.objects.new('GEO-target', None)

# 2. Do the work
# ...

# 3. Report
print(f"done:GEO-target {len(obj.data.vertices) if obj.data else 0}")

Naming conventions (apply to everything you create)

Prefix	Meaning
GEO-	Geometry / mesh objects
MAT-	Materials
LGT-	Lights
CAM-	Cameras
ARM-	Armatures (rigs)
COL-	Collections
WGT-	Custom bone shapes / widgets

Suffix .L / .R for left/right. Examples: GEO-sword_blade, MAT-steel_brushed, LGT-key.

Validation rule of thumb

After significant work, call mcp__blender__get_scene_info and verify:

• Expected objects exist with correct names.
• Object counts make sense (no runaway duplication).
• Polycount roughly matches target.

Before reporting success on a render or export, confirm the file actually exists (use Bash: ls -la /path/to/output).

When to load deeper references

• references/assembly-order.md — the canonical scene-assembly sequence, time budgets, recovery patterns. Load when planning a multi-step pipeline or when the user asks "what's the right order?".
• references/intent-routing.md — fuller intent-to-skill mapping with edge cases. Load when the request is ambiguous and you need to disambiguate.
• references/code-execution-rules.md — detailed rules for execute_blender_code (namespace, timeouts, stdout capture). Load when tracking down execution errors.

Reporting back to the user

When work is done, report concretely:

• ✅ Created: list objects + polycounts.
• ✅ Lit: list lights + their roles.
• ✅ Rendered: file path + size + dimensions + render time.
• ⚠️ Warnings: any auto-decimation, naming conflicts, fallback materials.

Example:

Created GEO-sword_blade (1 240 verts), GEO-sword_grip (320 verts).
Materials: MAT-steel_brushed, MAT-leather_dark.
Lit with LGT-key (warm 3200K), LGT-fill (cool 5500K), LGT-rim (cool blue).
Rendered to /tmp/sword_hero.png (1920×1080, 2.3 MB, 38 s with 256 samples + OptiX denoise).

Failure modes — what to do when…

Problem	Action
MCP timeout	Break the failing chunk into smaller pieces
Code execution error: <line>	Read the error; fix that one line; retry
Object not found in next call	You used a Python var instead of bpy.data.objects['name']
Render took too long	Reduce samples, enable adaptive sampling, lower resolution
File not at expected path	Use absolute paths; verify with Bash ls
Material looks wrong after export	You used non-Principled-BSDF nodes; rebuild material with Principled only
'Action' object has no attribute 'fcurves'	Blender 5.x layered Actions; walk action.layers[].strips[].channelbags[].fcurves instead. See blender-animation Recipe 3 for the compat helper.
BLENDER_EEVEE_NEXT rejected	Blender 5.x renamed it back to BLENDER_EEVEE. See blender-rendering Recipe 3 for the try/except fallback.
KeyError: 'Subsurface IOR' (or other input names)	Blender 5.x marks some BSDF inputs enabled=False (currently Weight, Subsurface IOR); they're reachable by iteration but not string-key lookup. See blender-materials Recipe 9 for the set_input helper.
Error: Cannot render, no camera	scene.camera is None. Always run the ensure_camera() guard before any render — see blender-rendering Recipes 5 / 6. The orchestrator must check this before chaining to render even if the user's prompt didn't ask for a camera explicitly.
User reports "scene is grey / no materials visible" while looking at Blender's viewport	Blender viewport defaults to Solid shading mode which ignores materials. The render is correct; only the viewport looks grey. After every scene assembly, set viewport to Material Preview: space.shading.type = 'MATERIAL'; space.shading.use_scene_lights = True; space.shading.use_scene_world = True
User reports "materials look flat / no texture"	Flat PBR colors lack surface variation. Add procedural textures (Noise/Voronoi → ColorRamp → Roughness or Bump) for steel scratches, hammered metal, leather grain, etc. See blender-materials Recipe 12 (procedural wood) for the pattern.
Subject looks wrongly proportioned (e.g. blade too short, chair too narrow)	The orchestrator skipped the dimension lookup. Always read references/common-object-dimensions.md BEFORE generating modeling code. Don't guess.
User asks for a "human" / "character" / "face" / "person"	Pure-recipe primitives produce a recognisable silhouette only, NOT a human face. Suggest one of: (a) mcp__blender__download_polyhaven_asset / download_sketchfab_model / generate_hyper3d_model_via_text for an actual human base mesh, then chain materials + lighting + render; (b) commission a Blender character artist (see prompts/04-blender-workflow.md). Do NOT pretend a sphere-with-features looks human — it doesn't. See references/common-object-dimensions.md "Characters / avatars" section.
Elongated subject renders as a thin pole instead of a recognisable shape	Camera viewing the thin axis of an elongated object. Rotate the object so its broad axis faces the camera. See blender-modeling "Critical: axis orientation for elongated objects".
Blade/spike has a "chiseled flat" tip instead of a point	Top vertices were scaled toward zero but not merged. Use the proper tapering recipe in blender-modeling ("Critical: tapering to a point") — collapse top verts to centerline AND remove_doubles.
Coloured glass renders flat/metallic instead of "glass-like"	Tint set on Base Color of Principled BSDF only. Real coloured glass needs Volume Absorption for depth-based tint. See blender-materials Recipe 6b. Also: Roughness=0.0 produces mirror-flat highlights that look metallic — use 0.02–0.05 instead.
Glass renders black on the inside	transmission_bounces too low. Default 12 is insufficient for thick or layered glass. Set scene.cycles.transmission_bounces = 24.

What this skill is NOT for

• Heavy custom GPU work / writing a render engine (use Blender's existing engines)
• Real-time game logic (use Unity / Unreal directly)
• Sculpting strokes from natural language (sculpting is gestural; use brushes interactively)
• Things outside Blender's capabilities (CAD precision modeling — use FreeCAD; CFD simulation — use Blender's Mantaflow only for VFX-quality, not engineering)

When the user asks for these, redirect them politely and explain.