Blender Agent Core

This skill is a ROUTER + procedure. The deep knowledge lives in knowledge/ — load exactly the file you need, do not recall it from memory. The root operating rules are in AGENTS.md (precedence: .project-agent.md > AGENTS.md > this skill). The .agents/skills/ copy is the source; .claude/skills/ is a mirror that must be kept in sync.

0. Routing by task

Read the hard rules every session (state explicitly which are ENFORCED vs MANUAL). Deliver results per revision-bound acceptance.

1. Knowledge routing (mandatory)

At the start of every Blender task, read the 3 foundation files if they are not already in context: knowledge/00-foundations/blender-version-matrix.md, bpy-scripting-core.md, agent-workflow-loop.md. Then python3 scripts/blender-knowledge.py list → route <workflow-id> to obtain the reading pack (skill blender-knowledge-workbench); load only the part you need. knowledge/INDEX.md is an on-demand lookup, not a must-read. loads_with is a one-hop hint, not a recursive load (one hop ≈ 40–50k tokens).

2. Loop (R1–R8 condensed — full version in agent-workflow-loop.md)

1. Contract first — purpose first (render-only / print / both, default both), then spec.json for a production part; fidelity contract for a reference; missing numbers → request-input.
2. Decompose — scene graph → one file per pass, ≤ ~80 lines, one purpose.
3. Assert every step — a pass ends with rt.emit_ok(step, **postconditions); the postcondition must FAIL if the step silently no-ops; operator return must be {'FINISHED'}. 3b. Form gate closes phase 2 (build phases: 1 blockout · 2 form + interfaces · 3 detail + materials · 4 studio + composition · 5 delivery) when purpose is print/both — temporary identity bake + spec from measurement + production-gate.py exit 0 before any material/studio work; delivery media only after PASS or an owner waiver (GATE WAIVED <time> "<owner words>"); final gate at delivery. Verification imagery stays mandatory and ungated but cheap (≤ 512 px / low-sample, ≤ ~2 min GPU per pass); costlier imagery is delivery media.
4. Non-destructive scaffold — the lib's scaffold() reads first and writes only when factory-default or force=True; never reset the scene being worked on.
5. Screenshot with intent — write down the expectation and what would falsify it BEFORE looking.
6. 2 failures on the same step → change the CLASS of approach; 3 failures → request-input.
7. Checkpoint (checkpoint(tag)) before every destructive op (boolean, apply, join).
8. Know the handoff boundary — fine weight painting, facial rig, art direction: flag early.

3. Verify ladder (cheap → expensive; if a number answers the question, do not spend an image)

import sys; sys.path.insert(0, "<ROOT>/scripts")
import agent_runtime as rt; lib = rt.load_lib("<ROOT>/scripts/agent-verify-lib.py")

1. Numbers: assert_exists, tri_count, world_bbox, has_material, fcurve keys — plus the postconditions in AGENT_OK.
2. framing(obj) → preview_render(engine="EEVEE"|"CYCLES") (≈0.1–0.2 s at 128–256px on a small scene, restores state) → frame_stats() (stdev < 0.01 = flat frame, needs diagnosis).
3. Viewport screenshot (MCP) — composition, "does it look like it".
4. Low-sample Cycles preview — real material/lighting.
5. Comparison sheet (scripts/make-comparison-sheet.sh) — when a reference image exists.
6. Turntable (scripts/turntable-preview.py) — guards against the "cardboard cutout" look.
7. Part production: python3 scripts/production-gate.py --scene <blend> --spec <spec.json> --report <out.json> exit 0; attach the report to the build. The gate proves topology/dimensions/screening numbers — it does not prove load, real fit, or thermal duty.

Measured on this machine: cold start 0.5 s, 256px preview ≈ 0.4–2 s. Verification is cheap; the ladder order follows information value, not cost.

4. Execution modes (check in order)

1. MCP tools (addon Connected): rt.run_file("/abs/pass.py") — full traceback inside AGENT_FAIL; a fresh namespace per call, reload helpers with rt.load_lib (cached by sha). Read the scene read-only before mutating.
2. Socket bridge when the MCP tool is not loaded: python3 scripts/blender-socket-client.py execute_code --file pass.py (exit 0/1/2/3 per the sentinel; output is not truncated).
3. Headless for batch/fault-test/gate: bash scripts/headless-run.sh pass.py (--factory-startup --disable-autoexec --python-exit-code 3; exit follows the sentinel). Supply a sheet/preview after every pass; when the build is finished, open the right file for the user. General rule: decide from the last line AGENT_OK/AGENT_FAIL; a timeout after sending a mutation = unknown → read the state before resending; a single writer for the GUI.

5. Failure quick-map