blender-scene-setup — Claude Code skill for Blender scenes
The blender-scene-setup Claude Code skill sets up and audits Blender scenes. It runs while starting a project, organizing a .blend file, or preparing a handoff or export.
MIT 558 installs ★ 2,624 updated 2026-11-13
npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a claude-codeWhat blender-scene-setup does
The skill checks scene units, scale, object names, collections, origins, images, and orphaned data. It uses scripts/scene_audit.py for the audit; --fix purge scale paths should only be used on files the team owns.
It defines an asset collection layout and naming patterns for meshes, materials, and textures, and covers linking or appending data from libraries. Collection Exporters are available from Blender 4.2. Scene units use meters with Unit Scale 1.0.
Before delivery, purge orphaned data and make image paths relative or pack them into the .blend file. Helper objects must also be excluded from export collections; hiding them in the viewport alone does not do that.
What it helps with
- audit scene scale and measurement units
- sort an asset into named collections
- rename objects to match project conventions
- find broken image paths and orphaned data
- prepare a collection for export or handoff
Example prompts for the agent
- Audit
crate.blendand list the scene issues. - Organize the asset into collections and rename meshes with the
SM_<Name>pattern. - Prepare the Blender file for handoff by checking image paths and orphaned data.
How to install blender-scene-setup
1Skills CLI (Vercel)
npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a claude-code2Manually: put the files in place
~/.claude/skills/blender-scene-setup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/blender-scene-setup/
1Skills CLI (Vercel)
npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a codex2Manually: put the files in place
.agents/skills/blender-scene-setup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a cursor2Manually: put the files in place
.cursor/skills/blender-scene-setup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install EL4CTEO/blender-skills skills/blender-scene-setup2Manually: put the files in place
.github/skills/blender-scene-setup/SKILL.md1Skills CLI (Vercel)
npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a gemini-cli2Platform CLI
gemini skills install https://github.com/EL4CTEO/blender-skills --path skills/blender-scene-setupManually: put the files in place
.devin/skills/blender-scene-setup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about blender-scene-setup
How do I install blender-scene-setup in Claude Code?
Run npx skills add EL4CTEO/blender-skills --skill blender-scene-setup -a claude-code. The skill file is at ~/.claude/skills/blender-scene-setup/SKILL.md.
What does blender-scene-setup do?
It audits and organizes Blender scenes, covering scale, collections, naming, origins, library data, and image paths. It also describes preparing scene data for export and handoff.
Which Blender version supports Collection Exporters?
Collection Exporters are available in Blender 4.2 and later.
Source text
SKILL.md · MIT
---
name: blender-scene-setup
description: Set up and audit Blender scenes the way studios do - units and real-world scale, collection layout, naming conventions (SM_/SK_/T_/M_), origins, linking vs appending, library overrides, asset libraries and catalogs, collection exporters, orphan/path cleanup. Use when starting a project, organizing a .blend, or before handoff/export.
license: MIT
metadata:
author: blender-agent-skills
version: "1.2.0"
---
# Scene Setup & Hygiene
The execution model and verification steps are in `blender-core`.
## Procedure
1. Run `scripts/scene_audit.py` (add `--fix purge scale paths` only on files you own). It reports units, unapplied/negative scale, default names, objects in the scene root, missing images, orphans and far-off origins.
2. Set units: Metric, Unit Scale **1.0**, Length meters. Keep 1.0 even for Unreal/Roblox, because exporters handle the conversion (see `blender-export-pipelines`).
3. Build the collection layout (below). Every object must be in a named collection, never the scene root.
4. Name everything with the conventions below. Rename after every duplicate or join so no `.001` suffixes remain.
5. Set origins: props at the bottom-center (they sit on the ground at Z=0), characters at world origin between the feet, doors/hinges at the pivot.
6. Apply rotation and scale on meshes (Ctrl+A). Keep location unless the asset should export at the origin.
7. Re-run the audit. It's done when `issues` is empty or every remaining issue is intentional and explained.
## Collection layout (one asset per .blend, or one collection per asset)
```
ASSET_Crate
├── Crate_high # sculpt / subdiv source (exclude from export)
├── Crate_low # game mesh(es) SM_Crate, SM_Crate_LOD1..
├── Crate_bake # cages, bake helpers
├── Crate_collision # UCX_SM_Crate_00 (UE) / Crate-col (Godot)
└── Crate_ref # reference images/blockout (hide_render)
```
Use **Collection Exporters** (4.2+) to define the export once per collection, then re-export with one call:
```python
with bpy.context.temp_override(collection=col):
bpy.ops.collection.exporter_add(name="IO_FH_gltf2")
ex = col.exporters[-1]; ex.export_properties.filepath = "//export/SM_Crate.glb"
with bpy.context.temp_override(collection=col):
bpy.ops.collection.exporter_export(index=len(col.exporters) - 1)
```
`bpy.ops.wm.collection_export_all()` re-runs every collection exporter. 5.3: glTF exporters set the origin with `collection_center_mode` (`WORLD_ORIGIN`, `CENTER_MASS`, `OBJECT_POSITION`, `INSTANCE_OFFSET`). Collections also get one **importer** (USD only, `collection.importer_add` / `importer_import`) whose settings are saved in the .blend.
## Naming conventions (Unreal-style, accepted by all engines)
| Type | Pattern | Example |
|---|---|---|
| Static mesh | `SM_<Name>[_LOD#]` | `SM_Crate_LOD1` |
| Skeletal mesh / rig | `SK_<Name>` / `RIG_<Name>` (armature object `Armature` or `root`) | `SK_Hero` |
| Material | `M_<Name>` / instance `MI_<Name>` | `M_Wood_Oak` |
| Texture | `T_<Name>_<Suffix>`: `_BC` base color, `_N` normal, `_ORM` (R=AO G=Rough B=Metal), `_E` emissive, `_M` mask | `T_Crate_ORM` |
| Collision | UE `UCX_<Mesh>_##`, Godot suffix `-col`/`-colonly`/`-convcolonly` | `UCX_SM_Crate_00` |
| Bones/sides | `.L`/`.R` suffix (Blender mirror tools depend on it) | `upper_arm.L` |
| Actions | `<Rig>_<Clip>` | `Hero_Run` |
Use ASCII only, no spaces, and PascalCase or snake_case consistently across the project.
## Real-world scale reference (meters)
Door 2.0–2.1 × 0.9 · ceiling 2.4–2.7 · table 0.75 · chair seat 0.45 · counter 0.9 · stair rise 0.18 / tread 0.28 · adult human 1.7–1.8 (eyes 1.6) · car 4.5 × 1.8 × 1.5. Roblox: 1 stud ≈ 0.28 m; default character ≈ 5 studs tall. Wrong scale breaks physics, lighting falloff, DOF and texel density, so check `ob.dimensions` first.
## Linking, appending, overrides
- **Append** (`libraries.load(link=False)`) makes a local copy. Use it for one-off reuse.
- **Link** (`link=True`) is read-only, updates from the source and is what pipelines use. To edit a linked collection, add a library override: `ob.override_hierarchy_create(scene, view_layer, do_fully_editable=False)`. Only overridable properties (transforms, pose, and anything marked overridable) can change.
- Keep library paths relative (`//`). Check `bpy.data.libraries` for broken paths.
## Asset libraries
- Mark: `ob.asset_mark(); ob.asset_generate_preview()`. Metadata goes in `ob.asset_data` (`author`, `description`, `license`, `tags.new("wood")`, `catalog_id`).
- Catalogs live in `blender_assets.cats.txt` at the library root, one line per catalog: `UUID:Path/Sub:Simple Name`.
- Register a library with `prefs.filepaths.asset_libraries.new(name=..., directory=...)`. 5.2+: remote libraries via `use_remote_url` + `remote_url`. In 5.2 `active_asset_library` indices are offset by 2 ("All", "Essentials").
- Import method per library: `LINK`, `APPEND`, `APPEND_REUSE` (default; reuses already-appended data).
## Hygiene rules
- Purge orphans before shipping (`bpy.data.orphans_purge(do_recursive=True)`). Use fake users only on purpose.
- Image paths: relative (`file.make_paths_relative`), or pack for single-file delivery (`file.pack_all`).
- Never ship multi-user mesh data that has an unapplied per-object scale. Instances are fine, but bake scale before export.
- Hide helpers with `hide_render=True` **and** exclude them from export collections; viewport hiding alone isn't enough.
- One active scene per file for delivery. Extra scenes confuse exporters (`use_active_scene`).
© blender-agent-skills · MIT · EL4CTEO/blender-skills