A Blender BPY skill that helps smaller LLMs build better 3D models

A large, battle-tested SKILL.md for driving an AI coding agent through headless Blender — modeling, materials, lighting, rendering, and export — with the goal of a first-draft delivery that already clears a real quality bar, not a rough draft that needs three more rounds of "make it better."

🦫 Built as part of Capybala, an upcoming AI agent desktop app — this skill is one of its built-in capabilities, shared here on its own.

When GPT-6 ASTRA shipped, timelines everywhere filled up with people showing off startlingly good 3D generations — full product renders, entire buildings, whole scenes, seemingly for free. It was hard not to wonder: could a cheap, fast model with no special 3D training do anything close?

Not GPT-6-tier — that was never the bar. The real question was whether it could beat the usual outcome of "ask an LLM to write some bpy code and hope for the best," which is normally geometry that doesn't quite line up, materials that read as plastic regardless of what they're supposed to be, and a camera framed by guesswork.

This skill is what came out of chasing that question with DeepSeek V4.1 Flash specifically — a small, inexpensive model, nothing exotic. Left alone, it produces exactly the rough outcome above. Run through this skill's Stage A → B → C workflow (plan the component list before touching geometry, build against calibrated camera/lighting/material presets, then self-review against measured render statistics before calling it done) it produces the gallery below instead.

Is it GPT-6 ASTRA? No, and nothing here claims that. But for a model with no 3D specialization at all, the gap between "unassisted" and "with this skill" is the whole point of building it.

All gallery images were generated by Capybala's own agent runtime (not yet public) driving DeepSeek V4.1 Flash through this skill. The skill itself doesn't depend on that agent — see Using this with an agent — it works the same way with any coding agent that can run Python and read/write files.

• Every image below was made with DeepSeek V4.1 Flash — not a smarter or more expensive model. Point a different model at this skill and results will move in either direction: a stronger model may follow its judgment calls better and produce cleaner output; a weaker one may need more correction rounds or fall short of what's shown here. Nothing in this gallery is a guarantee for whatever model you use.
• This gallery is curated, not representative. These are the outcomes worth showing off, picked out of a larger set of attempts. Plenty of other runs did not turn out this well — that's normal for a tool whose job is scaffolding a model's judgment, not replacing it.
• Two categories are a known, current weak point: cars/vehicles and human figures. Vehicle bodywork (compound curves, panel gaps, believable proportions) and human anatomy are both areas where this skill's technique library is thin and results are inconsistent — expect a rougher outcome, more manual correction, or an outright miss more often than with the product/architecture/hard-surface subjects shown here. The roadster below is a case that happened to land well, not a representative baseline for vehicles in general.

| World Trade Center towers | Mechanical dive watch | Two-group espresso machine | | Vintage roadster bicycle | Cargo delivery bike | Leifeng Pagoda | | Nova Tower — office highrise | 20-floor residential tower | Modular space station | | Launch vehicle on the pad | Chrome desk fan | |

The last image above is an intermediate exposure-calibration render, kept as-is — a small, honest look at the self-correction loop this skill runs before a scene ships, not a mistake we're hiding.

The full-resolution .blend project files for every scene above (plus these extra angles) are packaged as a downloadable asset on this repo's Releases page — open them in Blender 5.1 yourself, poke at how each scene is actually built.

This isn't a short prompt. It's a full operating manual plus a supporting code library:

• SKILL.md — the manual an agent reads before touching Blender: the Stage A → B → C workflow mentioned above, a verified Blender 5.1 API-drift table, camera/lighting/exposure presets calibrated against real render output, and a long list of "this will look wrong and here's the fix" rules for the visual failure modes that are easy to miss (interpenetrating geometry, floating parts, flat/lifeless materials, wrong camera framing, and more).

• assets/*.py — a plain bpy Python library (materials, parametric shapes, buildings, roads, nature/terrain, detail work, triview reconstruction from reference images, and a geometry/measurement toolkit) that an agent calls into instead of hand-rolling primitives every time. No app dependency — it's ordinary Blender Python, runnable by anyone with Blender installed.

• assets/anatomy/ — component checklists per product/building/vessel category (e.g. "a mechanical watch has these parts, don't build a hollow shell") so nothing obvious gets skipped.

• assets/styles/ — named design-style reference cards (architects, industrial-design lineages, genre looks) with concrete proportions/materials/color values instead of vague mood words.

• assets/examples/ — worked end-to-end examples per subject type.

• assets/scene_pkg/ — a structured scene-package format (config/layout/geometry/materials/assertions) for scenes that outgrow a single script.

• Blender 5.1.x (verified against 5.1.2; other 5.1.x builds should be close, see the version-drift warning at the top of SKILL.md )

• Python 3 (Blender's bundled interpreter is sufficient for the assets/*.py library; a separate script likeassets/component_measure.py runs viablender --background --python ... )

• Optional: ahujasid/blender-mcp (MIT) if you want interactive control from an MCP-capable client instead of pure headless scripting —SKILL.md §0–§1 cover both paths, including a six-tierblender.exe path resolver (assets/find_blender.ps1 , Windows) that avoids hard-coded install paths.

SKILL.md was written for an agent running inside Capybala's own tool set, so a number of its instructions call specific native tool names (read_image_native, run_python_native, read_file_native, write_file_native) — every one of those call sites also notes the equivalent operation for another platform right where it appears. For a human following the guide directly, or for wiring this into a different agent harness, those instructions map onto ordinary operations: "look at this image," "run this Python," "read/write this file." The actual Blender/bpy technique content — everything under assets/ — has no such dependency and works standalone.

This also follows the general skill-file convention used by Claude Code and other agent platforms that support loadable skills — add the standard YAML frontmatter (name/ description) to the top of SKILL.md and drop the folder into .claude/skills/ (or your platform's equivalent) to use it there directly.

SKILL.md itself is written in Traditional Chinese (code, function names, and API references throughout are English, as Python and Blender require — only the explanatory prose is Chinese). That's deliberate for this release, not an oversight: a machine-translation pass risks silently corrupting a threshold number, a conditional, or a cross-reference between sections, and that hasn't been checked yet. It doesn't affect usability — any capable AI agent reads Chinese natively, so nothing here requires you to read Chinese. If you'd like it in English or another language for your own reading, just ask your agent to translate it; the technical content translates cleanly, it's just not been done for this release yet.

A few specific things in here that go beyond "a big prompt telling the model to be careful":

Geometry QA that actually measures, instead of asking the model to eyeball it. build_template.py ships automated audits that run after every build: audit_interpenetration() scans object pairs for real overlap (AABB fast-path, with an optional BVH mesh-level mode for snug mechanical fits — caliper-on-brake-disc, wheel-on-tire — where bounding-box overlap alone is just noise); audit_floating() raycasts every object's base for support, but knows the difference between "sitting on something" and "bolted to the side of something" (mark_side_attached()/ mark_joint_attached() route cantilevered or fastened parts to a surface-gap check instead of a gravity check, so a wall-mounted sign doesn't get flagged as floating); audit_spacing() catches the one object in a repeated array whose position quietly drifted. These aren't advisory — results are written to a scene-state field Stage C is required to check, and the whole thing self-tunes its tolerance to the subject's actual size (a 138mm camera and a 40-story tower don't get the same millimeter budget).

A manufacturing mental model instead of "stack some primitives." The skill treats geometry the way real objects are actually made: openings are boolean-difference cuts with real wall thickness (not "just don't build a wall there"), edges get a deliberate chamfer/fillet radius scaled to the object's size (not Blender's zero-bevel default), and anything a lathe would actually turn — watch crowns, dial rings, camera barrels, bottle caps — gets built with a revolve-profile function instead of a plain cylinder with a bevel modifier, because a real turned part's radius changes continuously along its axis in a way a stretched-and-bevelled cylinder structurally can't reproduce.

Exposure is a pass/fail gate, not a vibe check. Every scene type (studio, outdoor golden-hour, night) has a numeric target luma band, and a render outside it fails automatically before it ever reaches a human. Lighting energy comes from presets calibrated against real render output and scaled to the subject's bounding box rather than copy-pasted absolute numbers, and a separate mean-vs-median check catches the case where one bright highlight (a lit window, a sign) drags the average into the passing range while the rest of the frame is sitting in near-black.

Rebuilding a real object is treated as a measurement problem, not a guessing one. When there's a real-world subject to match, reference material gets graded into four evidence tiers — from official orthographic drawings down to spec-numbers-only — each with an explicit ceiling on what it's allowed to prove, so a rough photo can inform proportions without ever being cited with the same confidence as a dimensioned drawing. The matching pipeline (calibrate → extract silhouette → loft → closed-loop verify) cross-checks the planned component list against the measured geometry twice — once before building, once after — and a blueprint generator draws the measured outline back onto the original reference photo with numbered parts, so a correction can be "A-3 is wrong" instead of a paragraph describing coordinates.

MIT — see LICENSE.