Blender Kiln

A complete 3D asset production pipeline for Claude Code, powered by Blender MCP.

From a text brief to an optimized, export-ready GLB — in one session.

What it does

Kiln is a Claude Code skill that turns you into a 3D asset production studio. It orchestrates Blender (via MCP), AI generation (Hunyuan3D, Pollinations/FLUX), and marketplace search (PolyHaven, Sketchfab) into a single coherent pipeline.

[1] CONFIG → [2] BRIEF → [3] SOURCE → [4] IMPORT → [5] CLEANUP → [5b] TEXTURING → [6] OPTIMIZE → [7] EXPORT

Pipeline phases

Key features

• Multi-method creation: AI generation (Hunyuan3D 2.x — local or cloud), scripted modeling (Blender Python), geometry nodes, or marketplace sourcing
• Local AI generation: run Hunyuan3D-2 Mini on your machine — NVIDIA GPU for full pipeline, Apple Silicon for shape generation
• Environment auto-detection: /kiln setup scans your system and guides installation
• Reference images: provide an image per asset (path, URL, or drag-and-drop) — guides all creation methods (AI input, scripted proportions, texture assignment), enriches the brief, and enables post-export visual comparison
• Concept art input: text prompt (Pollinations/FLUX), image path, image URL, or nano-banana (optional)
• Smart recommendations: auto-suggests the best creation method based on asset type and style
• Material audit: detects procedural nodes that will be lost on GLTF export, proposes bake workflow
• Post-export validation: 8-point checklist (Babylon.js sandbox, Three.js console, material spot-check)
• Character support: T-pose enforcement, rigging patterns, bone validation, Blender 5.x bone collections
• Multi-asset sessions: cross-asset coherence (scale, materials, poly budget)
• Batch mode: wizard collects scene/theme/palette/reference images upfront, generates a YAML manifest, runner executes autonomously — ideal for overnight production or large asset sets
• Full logging: every asset produces a production log with copy-paste prompts

Running over Blender MCP

The skill drives a live Blender through the Blender MCP addon. Below is SM_Barrel built, cleaned and exported inside a running Blender session — object named to convention, sitting on Z=0, ready to export:

The MCP pass and the headless scripted pass agree to the byte — 111.9 kB GLB either way, same 2,202 triangles, same three materials.

Check the integrations before you search

All four integrations ship off, as shown here. That matters more than it looks: while an integration is off, the addon does not register its commands at all, so a search does not come back "disabled" — it comes back

Unknown command type: search_polyhaven_assets

which reads like a version mismatch and sends you hunting for the wrong problem.

get_polyhaven_status, get_sketchfab_status, get_hunyuan3d_status and get_hyper3d_status are registered unconditionally and return the fix step by step — including the Sketchfab API key, which nothing else surfaces. Iron rule 22 requires checking them first. Tick the boxes in the BlenderMCP panel of the 3D Viewport sidebar (press N if hidden), then reconnect.

Gallery

Fifteen props across three themes, modelled from scratch by script, cleaned, audited, rendered and exported — all headless, on one laptop, with no cloud service and no paid API.

What this gallery is, and is not. These assets were produced by the scripts in examples/gallery/, written to the skill's rules — see Which rules the scripts obey for the audit.

They were not produced by running the skill. The skill drives Blender over MCP and its core loop is interactive: get_scene_info() before each phase (rule 1), get_viewport_screenshot() after each modification (rule 2), and a prompt before anything destructive (rule 6). None of that is exercised here — this is blender --background --python, the scripted-modeling path only. Treat the gallery as reference output and a conventions check, not as end-to-end validation of the skill.

What the OPTIMIZE phase actually buys

Measured, not estimated — these are the sizes the commands below produced:

15 assets · 21,879 tris · 1456.2 kB raw → 132.7 kB after dedup/weld/Draco (91% smaller)

Forge

Sci-fi modular

Stylised nature

Draco wins on size; gltfpack's meshopt output is roughly twice as large but decodes faster on the client. Both are lossy, and both run as individual steps — never gltf-transform optimize, per iron rule 20.

Two things the intermediate sizes will tell you if you read them closely:

• weld makes the file bigger. It is a preparation step for Draco, not a size win on its own — don't ship its output.
• Only Draco survives a round trip into Blender. Verified by re-importing every variant:

EXT_meshopt_compression is a web runtime format: three.js and Babylon decode it, Blender's glTF importer does not. That error on import is expected, not a broken file — reach for _final.glb when you need the asset back in Blender, and for _packed.glb when shipping to a viewer that decodes meshopt.

Which rules the scripts obey

Audited against the iron rules and references/, honestly:

Reproduce it

cd examples/gallery
./run_gallery.sh                      # all three themes
THEMES="forge nature" ./run_gallery.sh

Needs Blender 4.4+ (measured on 5.0 and 5.2), plus gltf-transform, gltfpack and cwebp.

studio.py holds the shared rig (sRGB→linear palette, three-point lighting with a per-theme accent, camera fitting, cleanup, budget check, material audit, render, GLB export). assets.py has one builder per prop plus the theme registry. build.py drives a single asset and writes its log.

Two Blender API traps cost real debugging time here, because both fail silently:

• Principled BSDF inputs are linear, not sRGB. Feeding hex-picked values straight in washes everything out — linear 0.31 is sRGB 0.58, so a magenta lands as pale pink and rich wood as light tan. studio.srgb() converts.
• Writing obj.location does not refresh obj.matrix_world. Read it in the same breath and you get the previous transform, so a "sit it on Z=0" correction computes zmin = 0.0 and does nothing — leaving the asset half-buried under the ground plane. Flush with view_layer.update() first.

Commands

Requirements

Required

• Blender 4.4 or newer, with the Blender MCP addon running (port 9876). Install the addon with uvx blender-mcp install-addon.

  4.4 is a hard floor, not a preference. Layered actions arrived in 4.4, and the animation code here reaches F-curves through action.layers[].strips[].channelbag(); on 4.0–4.3 that path does not exist. Everything in this repository is measured on 5.0 locally and 5.2 LTS in CI — 4.4 to 4.5 satisfy the API but are untested, so treat them as unverified rather than supported.

3D Generation (choose one or both)

The MCP-native path is the one to start with: nothing to install, just a checkbox in the addon panel. The HF Space is verified live — 12 endpoints, /generation_all and /shape_generation — but a community Space can pause without notice, so the skill checks its runtime stage before connecting.

On Mac (Apple Silicon): local shape generation works via MPS, texture generation falls back to skill's Blender-based texturing. On Windows + NVIDIA GPU: full pipeline runs locally — shape + texture, zero cloud dependency.

Optional

• nano-banana MCP — alternative concept art generation via Gemini (requires API key with billing)
• gltf-transform — npm install -g @gltf-transform/cli (texture compression, Draco)
• gltfpack — npm install -g gltfpack (mesh simplification, LOD generation)
• Sketchfab API token — free account, for marketplace downloads
• Reality Converter / usdzconvert — not needed: Blender exports USDZ natively

Installation

As a Claude Code plugin (recommended)

/plugin marketplace add elithril/blender-kiln
/plugin install blender-kiln@blender-kiln

Then run /kiln setup to detect your environment and install what's missing.

As a standalone skill

git clone https://github.com/elithril/blender-kiln.git ~/.claude/skills/blender-kiln

Restart Claude Code, then run /kiln setup.

Layout

Once installed, the skill directory looks like this:

~/.claude/skills/blender-kiln/
├── SKILL.md
└── references/
    ├── ai-generation.md
    ├── batch-mode.md
    ├── setup-install.md
    ├── characters.md
    ├── cli-tools.md
    ├── export-targets.md
    ├── naming-conventions.md
    ├── sourcing-strategy.md
    ├── texturing-strategy.md
    ├── topology-rules.md
    ├── uv-materials.md
    └── validation-checklist.md

Skill structure

Total: ~3,833 lines of production-tested 3D pipeline knowledge.

Continuous checks

tools/verify_docs.py runs on every push (.github/workflows/verify.yml) and checks that this documentation is still true — text only, no Blender, a few seconds:

• iron rules form one unbroken 1..N sequence across SKILL.md and batch-mode.md
• every cited rule N exists and means what the citation claims
• the rule count above matches reality, and every line count in the structure table is within 15% of the file it describes
• every referenced file exists, and none point outside the plugin directory
• every README image resolves
• no bare pip install (it fails on any PEP 668 Python)
• the plugin manifest is valid and its source is a real directory
• documented commands use the invocable /kiln <sub> form

tools/test_verify_docs.py seeds each of those regressions and asserts the checker catches it — 12/12. Every case is a mistake that was actually made here, including two renumberings that left a reference pointing at the wrong rule.

tools/verify_blender.py (.github/workflows/blender.yml, weekly and on demand) re-checks what needed Blender to establish — the documented bpy API still exists, the Principled sockets the docs name are real, Rigify's deform-bone counts still match the tiers PHASE 5c routes on, geometry nodes still need the modifier applied before export, and USDZ still exports natively into a conforming archive. It also fails on any Blender DeprecationWarning reached by the docs or the gallery — its first run surfaced Material.use_nodes, slated for removal in 6.0. Each check guards a shipped bug; this notices when a Blender release makes one wrong again.

Iron rules

The skill enforces 31 rules (26 core + 5 batch-specific). Key ones:

1. Always get_scene_info() before each phase
2. Always get_viewport_screenshot() after each modification
3. Never hard-cap poly count — alert if out of range, never block
4. Never silently destroy — decimate/simplify always interactive
5. Always keep the .blend file — in compact mode, only original + final + .blend + log
6. Never export_apply=True for GLTF — modifiers balloon file size
7. Always run material export audit before GLTF export
8. Never use gltf-transform optimize — use individual steps
9. Always check integration status before searching a marketplace — a disabled integration answers Unknown command type, not "disabled"
10. Between batch assets, clear the scene by removing datablocks — never with read_homefile(), which resets the scene properties holding those flags
11. Rename every import to the naming convention, whatever its source — a marketplace download arrives under the source file's name
12. Frame the viewport before screenshotting it, or the verification shot shows an apparently empty scene
13. Never pick a rig without measuring vertices ÷ deform bones — a Rigify human needs ~3,200 vertices to be worth it

Output

Two storage modes, configurable at pipeline start:

Compact (default) — minimal footprint, .blend is the recovery point:

generated-assets/
└── wooden-chair/
    ├── wooden-chair_original.glb
    ├── wooden-chair_final.glb
    ├── wooden-chair.blend
    └── wooden-chair_log.md

Full — all intermediate files for debug/comparison:

generated-assets/
└── wooden-chair/
    ├── wooden-chair_original.glb
    ├── wooden-chair_clean.glb
    ├── wooden-chair_textured.glb
    ├── wooden-chair_optimized.glb
    ├── wooden-chair_final.glb
    ├── wooden-chair.blend
    └── wooden-chair_log.md

Batch mode — assets grouped under a batch folder with manifest and report:

generated-assets/
└── batch-corporate-office-2026-04-02/
    ├── batch-manifest.yaml
    ├── batch-report.md
    ├── desk/
    ├── chair/
    └── keyboard/

At the end of a multi-asset session, Kiln proposes a cleanup of intermediate files with per-asset size breakdown.

Contributing

Fixes are welcome — see CONTRIBUTING.md. One rule shapes it: claims must be measured, not reasoned. Fifteen bugs in this repository's own documentation were found by running it, and none of them were visible in the text.

License

MIT © Nicolas Dolphens