dotfiles/home/.agents/skills/blender/SKILL.md

name, description

name	description
blender-local	Build, edit, and render 3D scenes with the locally installed Blender on this Mac. Use when the user requests Blender work or an editable Blender scene.

Local Blender

Installed application

The verified executable is /Applications/Blender.app/Contents/MacOS/Blender (plural Applications, not /Application/Blender). It reported Blender 5.1.2 during the September 2026 pelican project. Check the executable if the installation changes; use this local app for Blender requests.

Working workflow

Write scene-building scripts in the task's work/ directory. Execute bpy scripts with Blender's bundled Python, not an ordinary Python interpreter:

/Applications/Blender.app/Contents/MacOS/Blender --background --python work/scene.py

For ordinary Python helpers outside Blender, use uv run. Set absolute output paths in the Blender script, create the destination directory, and save both the editable .blend and rendered PNG to the task's deliverable directory.

To edit a saved scene, call bpy.ops.wm.open_mainfile(filepath=...) before making changes. Only clear all objects when intentionally building a new scene. Prefer reusable functions or loading the existing .blend over executing fragments sliced out of earlier scripts.

This finalization pattern worked with the installed version; choose image dimensions and samples for the task:

scene = bpy.context.scene
scene.render.engine = 'CYCLES'
scene.cycles.samples = 64
scene.cycles.use_denoising = True
scene.render.resolution_x = 1600
scene.render.resolution_y = 1200
scene.render.resolution_percentage = 100
scene.view_settings.view_transform = 'AgX'
scene.render.image_settings.file_format = 'PNG'
scene.render.filepath = str(output_dir / 'scene.png')
bpy.ops.wm.save_as_mainfile(filepath=str(output_dir / 'scene.blend'))
bpy.ops.render.render(write_still=True)

Use roughly 32–48 samples for previews and 64–96 for a polished still with denoising as starting points. Do not assume GPU acceleration is configured. Saving before rendering preserves the scene if rendering fails.

Execution and diagnosis

• The first sandboxed launch in this project exited with code 139 before running the script and wrote blender.crash.txt in the system temporary directory. A retry through the approved unsandboxed execution mechanism succeeded. Treat this as an observed environment issue, not proof that every crash needs escalation. On a similar startup failure, inspect the output and request the applicable execution permission; if a permitted retry still fails, investigate rather than repeatedly escalating.
• A USD Arch_ValidateAssumptions warning accompanied that startup failure; it did not establish the root cause.
• Material.use_nodes and World.use_nodes emitted deprecation warnings in 5.1.2 but worked. They are expected to change in Blender 6; verify the installed API when upgrading.
• Background rendering can produce little output for tens of seconds. If execution returns a session ID, poll that session until completion instead of launching duplicate renders. Confirm the exit status and saved files.

Modeling and visual lessons

• Cylinders aligned with direction.to_track_quat('Z', 'Y'), beveled curves, UV spheres, and custom meshes worked well for stylized scene construction. Smooth shading does not fix a faceted silhouette: give focal shapes enough geometry. Cap exposed curve ends or cover them with modeled joints.
• Inspect the rendered image after meaningful changes. Check the silhouette, grip and pedal contacts, floating parts, frame cropping, shadows, and whether background details are actually visible. A successfully saved render is not visual QA.
• Avoid overlapping coplanar surfaces. The retained studio floor hid the new beach and ocean; coincident surfaces produced black bands. Remove obsolete geometry and deliberately separate surface heights. For a box, calculate the top as center Z plus half its height.
• Frame an orthographic camera deliberately: an infinite ground plane fills the background without a natural horizon. A distant sky backdrop perpendicular to the horizontal viewing direction can provide a level horizon. Check projected positions of the sun, clouds, and distant props; adding them does not guarantee they appear in frame.
• For a substantial quality improvement, prioritize coherent composition, character anatomy, materials, and light over adding more objects. Preview warm key light, cooler fill, and rim light; avoid washed-out colors and unlit distant props. Keep decorative details from obscuring the subject.

Deliver the inspected render inline and link the editable .blend using absolute paths. Preserve earlier versions when making major revisions unless the user requests replacement.